Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

$accumulator (operador de acumulador)

$accumulator

Define un operador de acumulación personalizado. Los acumuladores son operadores que mantienen su estado (por ejemplo, totales, máximos, mínimos y datos relacionados) a medida que los documentos avanzan a través del pipeline. Utiliza el operador $accumulator para ejecutar tus propias funciones en JavaScript y así implementar comportamientos que no estén soportados por el languaje del query MongoDB. Consulta también $function.

$accumulator está disponible en estas etapas:

Importante

La ejecución de JavaScript dentro de un operador de agregación puede disminuir el rendimiento. Utilice solo el operador $accumulator si los operadores de pipeline proporcionados no pueden satisfacer las necesidades de su aplicación.

El operador $accumulator tiene esta sintaxis:

{ $accumulator: { init: <code>, initArgs: <array expression>, // Optional accumulate: <code>, accumulateArgs: <array expression>, merge: <code>, finalize: <code>, // Optional lang: <string> }}
Campo
Tipo
Descripción

string o código

Función utilizada para inicializar el estado. La función init recibe sus argumentos de la expresión de arreglo initArgs. Puede especificar la definición de la función como código de tipo BSON o string.

La función init tiene la siguiente forma:

function (<initArg1>, <initArg2>, ...) { ... return <initialState>}

Derramar en el disco o ejecutar una query en un clúster fragmentado puede hacer que el acumulador se calcule como una fusión de varias subacumulaciones, cada una de las cuales comienza llamando a init(). Asegúrese de que tus funciones init(), accumulate() y merge() sean compatibles con este modelo de ejecución.

Arreglo

opcional. Argumentos pasados a la función init.

initArgs tiene la siguiente forma:

[ <initArg1>, <initArg2>, ... ]

IMPORTANTE: Cuando se use en una $bucketAuto etapa, initArgs no puede referirse a la clave de grupo (es decir, no se puede usar la sintaxis $<fieldName>). En cambio, en una etapa $bucketAuto, solo puedes especificar valores constantes en initArgs.

string o código

Función utilizada para acumular documentos. La función accumulate recibe sus argumentos del estado actual y de la expresión de arreglo accumulateArgs. El resultado de la función accumulate se convierte en el nuevo estado. Puedes especificar la definición de la función como código de tipo BSON o string.

La función accumulate tiene la siguiente forma:

function(state, <accumArg1>, <accumArg2>, ...) { ... return <newState>}

Arreglo

Argumentos pasados a la función accumulate. Puede usar accumulateArgs para especificar qué valores de campo pasar a la función accumulate.

accumulateArgs tiene la siguiente forma:

[ <accumArg1>, <accumArg2>, ... ]

string o código

Función utilizada para fusionar dos estados internos. merge debe ser un tipo BSON de string o código. merge devuelve el resultado combinado de los dos estados fusionados. Para obtener información sobre cuándo se llama a la función de fusión, consulte Fusionar dos estados con $merge.

La función merge tiene la siguiente forma:

function (<state1>, <state2>) { <logic to merge state1 and state2> return <newState>}

string o código

opcional. Función utilizada para actualizar el resultado del acumulador.

La función finalize tiene la siguiente forma:

function (state) { ... return <finalState>}

String

El lenguaje utilizado en el código $accumulator.

IMPORTANTE: Actualmente, el único valor admitido para lang es js.

Los siguientes pasos describen cómo el operador $accumulator procesa los documentos:

  1. El operador comienza en un estado inicial, definido por la función init.

  2. Para cada documento, el operador actualiza el estado según la función accumulate. El primer argumento de la función accumulate es el estado actual, y se pueden especificar argumentos adicionales en el arreglo accumulateArgs.

  3. Cuando el operador necesita fusionar varios estados intermedios, ejecuta la función merge. Para obtener más información sobre cuándo se llama a la función de fusión, consulte Fusionar dos estados con $merge.

  4. Si se ha definido una función finalizar, una vez que se hayan procesado todos los documentos y se haya actualizado el estado en consecuencia, finalizar convierte el estado en una salida final.

Como parte de sus operaciones internas, el operador $accumulator puede necesitar fusionar dos estados intermedios separados. La función merge especifica cómo el operador debe fusionar dos estados.

La función merge siempre combina dos estados a la vez. Si es necesario combinar más de dos estados, la combinación resultante de dos estados se combina con un único estado. Este proceso se repite hasta que se combinan todos los estados.

Por ejemplo, $accumulator puede necesitar combinar dos estados en los siguientes escenarios:

  • $accumulator Se ejecuta en un clúster fragmentado. El operador necesita fusionar los resultados de cada partición para obtener el resultado final.

  • Una sola operación de $accumulator supera su límite de memoria especificado. Si especifica la opción allowDiskUse, el operador almacena la operación en curso en disco y termina la operación en memoria. Una vez que la operación finalice, los resultados del disco y la memoria se fusionan utilizando la función merge.

El orden con el que MongoDB procesa documentos para las funciones init(), accumulate() y merge() puede variar y podría diferir del orden en que esos documentos se especifican para la función $accumulator.

Por ejemplo, considera una serie de documentos donde los campos _id son las letras del alfabeto:

{ _id: 'a' },{ _id: 'b' },{ _id: 'c' }...{ _id: 'z' }

A continuación, considere un pipeline de agregación que ordena los documentos por el campo _id y luego utiliza una función $accumulator para concatenar los valores del campo _id:

[ { $sort: { _id: 1 } }, { $group: { _id: null, alphabet: { $accumulator: { init: function() { return "" }, accumulate: function(state, letter) { return(state + letter) }, accumulateArgs: [ "$_id" ], merge: function(state1, state2) { return(state1 + state2) }, lang: "js" } } } }]

MongoDB no garantiza que los documentos se procesen en orden clasificado, lo que significa que el campo alphabet no necesariamente se establecerá en abc...z.

Debido a este comportamiento, asegúrate de que tu función $accumulator no necesite procesar y retornar documentos en un orden específico.

Para usar $accumulator, debes habilitar el script del lado del servidor.

Si no utilizas $accumulator (o $function, $where o mapReduce), desactiva los scripts en el lado del servidor:

Consulta también ➤ Ejecutar MongoDB con opciones de configuración seguras.

MongoDB 6.0 mejora el motor interno JavaScript utilizado para JavaScript del lado del servidor, $accumulator, $function, y $where expresiones y de MozJS-60 a MozJS-91. Varias funciones de arreglos y strings obsoletas y no estándar que existían en MozJS-60 se eliminan en MozJS-91.

Los ejemplos de esta página utilizan datos del conjunto de datos sample_mflix. Para obtener más información sobre cómo cargar este conjunto de datos en la implementación autogestionada de MongoDB, consultar Cargar el conjunto de datos de muestra. Si realizó alguna modificación en las bases de datos de muestra, es posible que deba descartar y volver a crear las bases de datos para ejecutar los ejemplos de esta página.

Nota

Este ejemplo muestra cómo utilizar el operador $accumulator para implementar el operador $avg que ya admite MongoDB. El objetivo de este ejemplo no es implementar una nueva funcionalidad, sino ilustrar el comportamiento y la sintaxis del operador $accumulator con una lógica familiar.

La siguiente operación groups los documentos por rated, y utiliza $accumulator para calcular el imdb.rating promedio para cada calificación de contenido. La etapa $match restringe la entrada a las calificaciones de contenido G, PG, PG-13 y R, y excluye los documentos donde imdb.rating no es un double, como una string vacía:

db.movies.aggregate( [ { $match: { rated: { $in: [ "G", "PG", "PG-13", "R" ] }, "imdb.rating": { $type: "double" } } }, { $group: { _id: "$rated", avgRating: { $accumulator: { init: function() { // Set the initial state return { count: 0, sum: 0 } }, accumulate: function(state, rating) { // Define how to update the state return { count: state.count + 1, sum: state.sum + rating } }, accumulateArgs: [ "$imdb.rating" ], // Argument required by the accumulate function merge: function(state1, state2) { // When the operator performs a merge, return { // add the fields from the two states count: state1.count + state2.count, sum: state1.sum + state2.sum } }, finalize: function(state) { // After collecting the results from all documents, return (state.sum / state.count) // calculate the average }, lang: "js" } } } }, { $sort: { _id: 1 } }] )
[ { _id: 'G', avgRating: 6.628092243186578 }, { _id: 'PG', avgRating: 6.43525917926564 }, { _id: 'PG-13', avgRating: 6.404911676001717 }, { _id: 'R', avgRating: 6.456657633242984 }]

$accumulator define un estado inicial donde count y sum están ambos configurados a 0. Para cada documento que procesa el $accumulator, este actualiza el estado mediante:

  • Incrementando el count por 1 y

  • Agregar los valores del campo imdb.rating del documento al sum. La función accumulate puede acceder al campo imdb.rating porque se pasa en el campo accumulateArgs.

Con cada documento que se procesa, la función acumular devuelve el estado actualizado.

Una vez procesados todos los documentos, la función de finalización divide la sum de las calificaciones por el count de documentos para obtener el promedio. Esto remueve la necesidad de mantener un promedio calculado en ejecución, ya que la función de finalización recibe la sum y el count acumulados de todos los documentos.

Esta operación es equivalente al siguiente pipeline, que utiliza el operador $avg:

db.movies.aggregate( [ { $match: { rated: { $in: [ "G", "PG", "PG-13", "R" ] }, "imdb.rating": { $type: "double" } } }, { $group: { _id: "$rated", avgRating: { $avg: "$imdb.rating" } } }, { $sort: { _id: 1 } }] )
[ { _id: 'G', avgRating: 6.6280922431865825 }, { _id: 'PG', avgRating: 6.435259179265659 }, { _id: 'PG-13', avgRating: 6.404911676001723 }, { _id: 'R', avgRating: 6.456657633242999 }]

Puedes utilizar la opción initArgs para variar el estado inicial de $accumulator. Esto puede ser útil si, por ejemplo, desea:

  • Utilice el valor de un campo que no esté en su estado para afectar su estado, o

  • Establece el estado inicial a un valor diferente según el grupo que se procese.

Supongamos que una aplicación permite a los usuarios hacer query de estos datos para encontrar películas. Puede ser útil mostrar más resultados para la clasificación de contenido que el usuario prefiere. Para este ejemplo, la clasificación de contenido preferida del usuario es PG-13, que se pasa a la función init como userProfileRated.

La siguiente pipeline de agregación groups los documentos por rated. La operación utiliza $accumulator para mostrar un número diferente de películas de cada clasificación de contenido dependiendo de si la clasificación de la película coincide con la clasificación en el perfil del usuario:

Nota

Para ejecutar este ejemplo con una clasificación de contenido preferida diferente, reemplace "PG-13" en el arreglo initArgs con otro valor, como "R".

db.movies.aggregate( [ { $match: { rated: { $in: [ "G", "PG", "PG-13", "R" ] }, "imdb.rating": { $type: "double" } } }, { $sort: { "imdb.rating": -1, title: 1 } }, { $group: { _id: { rated: "$rated" }, movies: { $accumulator: { init: function(rated, userProfileRated) { // Set the initial state return { max: rated === userProfileRated ? 3 : 1, // If the group matches the user's rating, movies: [] // return 3 movies. Otherwise, return 1. } }, initArgs: [ "$rated", "PG-13" ], // Argument to pass to the init function accumulate: function(state, movieTitle) { // Define how to update the state if (state.movies.length < state.max) { state.movies.push(movieTitle); } return state; }, accumulateArgs: [ "$title" ], // Argument required by the accumulate function merge: function(state1, state2) { return { max: state1.max, movies: state1.movies.concat(state2.movies).slice(0, state1.max) } }, finalize: function(state) { // Adjust the state to only return the field we need return state.movies }, lang: "js" } } } }, { $sort: { "_id.rated": 1 } }] )
[ { _id: { rated: 'G' }, movies: [ 'Modern Times' ] }, { _id: { rated: 'PG' }, movies: [ 'Life' ] }, { _id: { rated: 'PG-13' }, movies: [ 'A Brave Heart: The Lizzie Velasquez Story', 'The Dark Knight', 'The Lord of the Rings: The Return of the King' ] }, { _id: { rated: 'R' }, movies: [ 'The Shawshank Redemption' ] }]

La función init define un estado inicial que contiene los campos max y movies. El campo max establece el número máximo de películas para ese grupo en particular. Si el campo rated del documento coincide con userProfileRated, ese grupo contiene un máximo de 3 películas. De lo contrario, si el campo rated del documento no coincide con userProfileRated, el grupo contiene como máximo una sola película. La función init recibe los argumentos rated y userProfileRated del arreglo initArgs.

Para cada documento que $accumulator procesa, se inserta el title de la película en el arreglo movies, siempre que ese título no exceda la longitud de movies respecto al valor max. Con cada documento que se procesa, la función acumular devuelve el estado actualizado.

La función merge define cómo fusionar dos estados. La función concatena los movies arreglos de cada estado, y el tamaño del arreglo resultante se limita mediante el uso del método slice() para asegurar que no exceda el valor de max.

Una vez procesados todos los documentos, la función de finalización modifica el estado resultante para que solo devuelva los títulos de las películas. Sin esta función, el campo max también se incluiría en el resultado, lo que no satisface ninguna necesidad de la aplicación.