Definición
$accumulatorDefine 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
$accumulatorpara 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.$accumulatorestá 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
$accumulatorsi los operadores de pipeline proporcionados no pueden satisfacer las necesidades de su aplicación.
Sintaxis
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 La función 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 | |
Arreglo | opcional. Argumentos pasados a la función
IMPORTANTE: Cuando se use en una | |
string o código | Función utilizada para acumular documentos. La función La función | |
Arreglo | Argumentos pasados a la función
| |
string o código | Función utilizada para fusionar dos estados internos. La función | |
string o código | opcional. Función utilizada para actualizar el resultado del acumulador. La función | |
String | El lenguaje utilizado en el código IMPORTANTE: Actualmente, el único valor admitido para |
Comportamiento
Los siguientes pasos describen cómo el operador $accumulator procesa los documentos:
El operador comienza en un estado inicial, definido por la función init.
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.
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.
Combinar dos estados con $merge
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:
$accumulatorSe 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
$accumulatorsupera su límite de memoria especificado. Si especifica la opciónallowDiskUse, 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.
Orden de Procesamiento de Documentos
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.
Javascript habilitado
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:
Para una instancia de
mongod, consulta la opción de configuraciónsecurity.javascriptEnabledo la opción de línea de comandos--noscripting.Para una instancia
mongos, consulta la opción de configuraciónsecurity.javascriptEnabledo la opción de línea de comandos--noscripting.En versiones anteriores, MongoDB no permite la ejecución de JavaScript en instancias de
mongos.
Consulta también ➤ Ejecutar MongoDB con opciones de configuración seguras.
Funciones de string y arreglo no compatibles
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.
Ejemplos
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.
Utiliza $accumulator para implementar el $avg operador
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 }]Comportamiento
$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
countpor 1 yAgregar los valores del campo
imdb.ratingdel documento alsum. La función accumulate puede acceder al campoimdb.ratingporque 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.
Comparación con $avg
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 }]Usa initArgs para variar el estado inicial por grupo
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' ] }]Comportamiento
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.