Definición
aggregateRealiza la operación de agregación utilizando el Canal de agregación. Este canal permite a los usuarios procesar datos de una colección u otra fuente mediante una secuencia de manipulaciones basadas en etapas.
Tip
En
mongosh, este comando también se puede ejecutar a través de los métodos auxiliaresdb.aggregate()y o condb.collection.aggregate()watch()el método auxiliar.Los métodos asistente son convenientes para usuarios de
mongosh, pero es posible que no proporcionen el mismo nivel de información que los comandos de base de datos. En los casos en que no se necesite la conveniencia o se requieran campos de retorno adicionales, utiliza el comando de base de datos.
Compatibilidad
Este comando está disponible en implementaciones alojadas en los siguientes entornos:
MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube
Importante
Este comando tiene soporte limitado en los clústeres Flex y M0. Para obtener más información, consulta Comandos no compatibles.
MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.
Sintaxis
Modificado en la versión 5.0.
El comando tiene la siguiente sintaxis:
db.runCommand( { aggregate: "<collection>" || 1, pipeline: [ <stage>, <...> ], explain: <boolean>, allowDiskUse: <boolean>, cursor: <document>, maxTimeMS: <int>, bypassDocumentValidation: <boolean>, readConcern: <document>, collation: <document>, hint: <string or document>, comment: <any>, writeConcern: <document>, let: <document> // Added in MongoDB 5.0 } )
Campos de comandos
El comando aggregate toma los siguientes campos como argumentos:
Campo | Tipo | Descripción | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| string | El nombre de la colección o vista que sirve como entrada para el pipeline de agregación. Utilizar | ||||||||||
| arreglo | Un arreglo de las etapas del pipeline de agregación que procesan y transforman el flujo de documentos como parte del pipeline de agregación. | ||||||||||
| booleano | Opcional. Especificar devolver la información sobre el procesamiento del pipeline. No disponible en transacciones multi-documento. | ||||||||||
| booleano | Opcional. Usa esta opción para anular
A partir de MongoDB 6.0, si Para obtener más detalles, consulte Los mensajes de registro del perfilador y los mensajes de registro de diagnóstico incluyen un indicador | ||||||||||
| Documento | Especificar un documento que contenga opciones que controlen la creación del objeto cursor. Debe utilizar el comando
| ||||||||||
| non-negative integer | Opcional. Especifica un límite de tiempo en milisegundos. Si no especifica un valor para MongoDB finaliza las operaciones que exceden su límite de tiempo asignado utilizando el mismo mecanismo que | ||||||||||
| booleano | |||||||||||
| Documento | Opcional. Especifica el nivel de consistencia de lectura. La opción Los posibles niveles de consistencia de lectura son estos:
Para obtener más información sobre los niveles de consistencia de lectura, consulta Nivel de consistencia de lectura. La etapa La etapa | ||||||||||
| Documento | Opcional. Especifica la intercalación a utilizar para la operación. La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento. La opción de intercalación tiene la siguiente sintaxis: Al especificar la intercalación, el campo Si no se especifica la intercalación, pero la colección tiene una intercalación por defecto (ver Si no se especifica ninguna intercalación para la colección o para las operaciones, MongoDB utiliza la comparación binaria simple usada en versiones anteriores para las comparaciones de strings. No puedes especificar varias intercalaciones para una operación. Por ejemplo, no puedes especificar diferentes intercalaciones por campo, o si realizas una búsqueda con un ordenamiento, no puedes usar una intercalación para la búsqueda y otra para el ordenamiento. | ||||||||||
| string o documento | Opcional. El índice que se utilizará para la agregación. El índice se encuentra en la colección/vista inicial sobre la cual se ejecuta la agregación. Especifique el índice ya sea por su nombre o por el documento de especificación del índice. El | ||||||||||
| any | Opcional. Un comentario proporcionado por el usuario para adjuntar a este comando. Una vez configurado, este comentario aparece junto a los registros de este comando en las siguientes ubicaciones:
Un comentario puede ser de cualquier tipo BSON válido (string, objeto, arreglo, etc.). Cualquier comentario establecido en un comando | ||||||||||
| Documento | Opcional. Un documento que expresa el nivel de confirmación de escritura a utilizar con la etapa Omitir para usar el nivel de confirmación de escritura por defecto con la etapa | ||||||||||
| Documento | Opcional. Especifica un documento que contiene una lista de variables. Esto le permite mejorar la legibilidad de los comandos al separar las variables del texto de la query. La sintaxis del documento es: La variable se establece en el valor devuelto por la expresión y no puede modificarse posteriormente. Para acceder al valor de una variable en el comando, se debe usar el prefijo de doble signo de dólar ( Para usar una variable como filtro de resultados en una etapa de Para un ejemplo completo usando Nuevo en la versión 5.0. |
Debe utilizar el comando aggregate con la opción cursor a menos que el comando incluya la opción explain.
Para indicar un cursor con el tamaño de agrupación por defecto, se debe especificar
cursor: {}.Para indicar un cursor con un tamaño de agrupación distinto al establecido por defecto, se debe utilizar
cursor: { batchSize: <num> }.
Para obtener más información sobre la canalización de agregación, consulte:
Sesiones
Para los cursores creados dentro de una sesión, no puedes llamar a getMore fuera de la sesión.
De manera similar, para los cursores creados fuera de una sesión, no puedes llamar a getMore dentro de una sesión.
Tiempo de espera de inactividad de la sesión
Los drivers de MongoDB y mongosh asocian todas las operaciones con una sesión de servidor, con la excepción de las operaciones de escritura no reconocidas. Para las operaciones no asociadas explícitamente a una sesión (es decir, mediante Mongo.startSession()), los drivers de MongoDB y mongosh crean una sesión implícita y la asocian con la operación.
Si una sesión está inactiva durante más de 30 minutos, MongoDB Server marca esa sesión como expirada y puede cerrarla en cualquier momento. Cuando MongoDB Server cierra la sesión, también finaliza cualquier operación en curso y cierra los cursores abiertos asociados con la sesión. Esto incluye cursores configurados con noCursorTimeout() o un maxTimeMS() mayor a 30 minutos.
Para las operaciones que devuelven un cursor, si el cursor puede estar inactivo durante más de 30 minutos, emita la operación dentro de una sesión explícita usando Mongo.startSession() y actualice periódicamente la sesión usando el comando refreshSessions. Consulte Tiempo de espera de inactividad de la sesión para obtener más información.
Transacciones
aggregate puede usarse dentro de transacciones distribuidas.
Sin embargo, las siguientes etapas no están permitidas dentro de las transacciones:
Tampoco puede especificar la opción explain.
Para los cursores creados fuera de una transacción, no puedes llamar a
getMoredentro de la transacción.Para los cursores creados en una transacción, no puedes llamar a
getMorefuera de la transacción.
Importante
En la mayoría de los casos, una transacción distribuida incurre en un costo de rendimiento mayor que las escrituras de documentos individuales, y la disponibilidad de transacciones distribuidas no debería ser un sustituto para un diseño de esquema efectivo. Para muchos casos, el modelo de datos desnormalizado (documento incrustado y matrices) seguirá siendo óptimo para tus datos y casos de uso. Es decir, en muchos casos, modelar tus datos de forma adecuada minimizará la necesidad de transacciones distribuidas.
Para consideraciones adicionales sobre el uso de transacciones (como el límite de tiempo de ejecución y el límite de tamaño del oplog), consulta también las consideraciones de producción.
Desconexión del cliente
Para la operación aggregate que no incluye las etapas $out o $merge:
Si el cliente que emitió aggregate se desconecta antes de que la operación se complete, MongoDB marca aggregate para su terminación usando killOp.
Configuración de query
Nuevo en la versión 8.0.
Puedes utilizar la configuración de query para establecer sugerencias de índice, fijar filtros de rechazo de operación y otros campos. Los ajustes se aplican a la forma de la query en todo el clúster. El clúster retiene la configuración después del apagado.
El optimizador de query utiliza la configuración del query como entrada adicional durante la planificación del query, lo que afecta al plan seleccionado para ejecutar el query. También puedes usar la configuración del query para bloquear una forma del query.
Para añadir configuraciones de query y explorar ejemplos, consulte setQuerySettings.
Puede agregar configuraciones de query para los comandos find, distinct y aggregate.
La configuración de query tiene más funcionalidades y se prefiere sobre los filtros de índice en desuso.
Para remover la configuración del query, utilice removeQuerySettings. Para obtener la configuración del query, utilice una etapa de $querySettings en una canalización de agregación.
Stable API
Cuando se debe utilizar Stable API V1:
No puede usar las siguientes etapas en un comando
aggregate:No se debe incluir el campo
explainen un comandoaggregate. Si se hace esto, el servidor devuelve un error APIStrictError.Al utilizar la etapa
$collStats, solo puede utilizar el campocount. No hay otros campos$collStatsdisponibles.
Ejemplo
Debe utilizar el comando aggregate con la opción cursor a menos que el comando incluya la opción explain.
Para indicar un cursor con el tamaño de agrupación por defecto, se debe especificar
cursor: {}.Para indicar un cursor con un tamaño de agrupación distinto al establecido por defecto, se debe utilizar
cursor: { batchSize: <num> }.
En lugar de ejecutar el comando aggregate directamente, la mayoría de los usuarios deben utilizar el asistente db.collection.aggregate() proporcionado en mongosh o el asistente equivalente en su driver. En 2.6 y versiones posteriores, el asistente db.collection.aggregate() siempre devuelve un cursor.
Excepto por los dos primeros ejemplos que demuestran la sintaxis del comando, los ejemplos de esta página utilizan el asistente db.collection.aggregate().
Agregación de datos con pipeline multi-etapas
Una colección articles contiene documentos como los siguientes:
{ _id: ObjectId("52769ea0f3dc6ead47c9a1b2"), author: "abc123", title: "zzz", tags: [ "programming", "database", "mongodb" ] }
El siguiente ejemplo realiza una operación aggregate en la colección articles para calcular el recuento de cada elemento distinto en el arreglo tags que aparece en la colección.
db.runCommand( { aggregate: "articles", pipeline: [ { $project: { tags: 1 } }, { $unwind: "$tags" }, { $group: { _id: "$tags", count: { $sum : 1 } } } ], cursor: { } } )
En mongosh, esta operación puede usar el asistentedb.collection.aggregate() como en el siguiente ejemplo:
db.articles.aggregate( [ { $project: { tags: 1 } }, { $unwind: "$tags" }, { $group: { _id: "$tags", count: { $sum : 1 } } } ] )
Usar $currentOp en una base de datos admin
El siguiente ejemplo ejecuta un pipeline con dos etapas en la base de datos admin. La primera etapa ejecuta la operación $currentOp y la segunda etapa filtra los resultados de esa operación.
db.adminCommand( { aggregate : 1, pipeline : [ { $currentOp : { allUsers : true, idleConnections : true } }, { $match : { shard : "shard01" } } ], cursor : { } } )
Nota
El comando aggregate no especifica una colección y en su lugar adopta la forma {aggregate: 1}. Esto se debe a que la etapa inicial $currentOp no obtiene la entrada de una colección. Produce sus propios datos que el resto del pipeline utiliza.
Se ha añadido el nuevo asistente db.aggregate() para asistir en la ejecución de agregaciones sin colección como esta. La agregación anterior también podría ejecutarse como este ejemplo.
Información sobre la operación de agregación
La siguiente operación de agregación establece el campo opcional explain en true para devolver información sobre la operación de agregación.
db.orders.aggregate([ { $match: { status: "A" } }, { $group: { _id: "$cust_id", total: { $sum: "$amount" } } }, { $sort: { total: -1 } } ], { explain: true } )
Nota
La salida explicativa está sujeta a cambios entre versiones.
Tip
db.collection.aggregate() Método
Interacción con allowDiskUseByDefault
A partir de MongoDB 6.0, las etapas de la canalización que requieren más de 100 megabytes de memoria para ejecutarse escriben archivos temporales en el disco de forma predeterminada. Estos archivos temporales duran mientras se ejecuta la canalización y pueden afectar el espacio de almacenamiento de la instancia. En versiones anteriores de MongoDB, se debía pasar { allowDiskUse: true } a los comandos find y aggregate para habilitar este comportamiento.
Los comandos individuales find y aggregate pueden anular el parámetro allowDiskUseByDefault de las siguientes maneras:
Se utiliza
{ allowDiskUse: true }para permitir la escritura de archivos temporales en el disco cuandoallowDiskUseByDefaultse establece enfalseSe utiliza
{ allowDiskUse: false }para prohibir la escritura de archivos temporales en el disco cuandoallowDiskUseByDefaultesté configurado entrue
Los mensajes de registro del perfilador y los mensajes de registro de diagnóstico incluyen un indicador usedDisk si alguna etapa de agregación escribió datos en archivos temporales debido a restricciones de memoria.
Agregación de datos especificando el tamaño de agrupación
Para especificar un tamaño inicial de agrupación, se debe especificar el batchSize en el campo cursor, como en el siguiente ejemplo:
db.orders.aggregate( [ { $match: { status: "A" } }, { $group: { _id: "$cust_id", total: { $sum: "$amount" } } }, { $sort: { total: -1 } }, { $limit: 2 } ], { cursor: { batchSize: 0 } } )
El documento { cursor: { batchSize: 0 } }, que especifica el tamaño del agrupación inicial, indica una primera agrupación vacía. Este tamaño de agrupación es útil para devolver rápidamente un cursor o un mensaje de error sin realizar un trabajo significativo en el servidor.
Para especificar el tamaño de agrupación para las operaciones getMore posteriores (después de la agrupación inicial), use el campo batchSize al ejecutar el comando getMore.
Especifica una intercalación
La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento.
Una colección myColl tiene los siguientes documentos:
{ _id: 1, category: "café", status: "A" } { _id: 2, category: "cafe", status: "a" } { _id: 3, category: "cafE", status: "a" }
La siguiente operación de agregación incluye la opción de intercalación:
db.myColl.aggregate( [ { $match: { status: "A" } }, { $group: { _id: "$category", count: { $sum: 1 } } } ], { collation: { locale: "fr", strength: 1 } } );
Para obtener descripciones sobre los campos de intercalación, consulta el Documento de intercalación.
Sugerencia de índice
Cree una colección foodColl con los siguientes documentos:
db.foodColl.insertMany( [ { _id: 1, category: "cake", type: "chocolate", qty: 10 }, { _id: 2, category: "cake", type: "ice cream", qty: 25 }, { _id: 3, category: "pie", type: "boston cream", qty: 20 }, { _id: 4, category: "pie", type: "blueberry", qty: 15 } ] )
Cree los siguientes índices:
db.foodColl.createIndex( { qty: 1, type: 1 } ); db.foodColl.createIndex( { qty: 1, category: 1 } );
La siguiente operación de agregación incluye la opción hint para forzar el uso del índice especificado:
db.foodColl.aggregate( [ { $sort: { qty: 1 }}, { $match: { category: "cake", qty: 10 } }, { $sort: { type: -1 } } ], { hint: { qty: 1, category: 1 } } )
Anular el nivel de consistencia de lectura por defecto
Para anular el nivel de consistencia de lectura por defecto, se debe utilizar la opción readConcern. El comando getMore utiliza el nivel readConcern especificado en el comando aggregate de origen.
No puede utilizar la etapa $out o la etapa $merge junto con el nivel de consistencia de lectura "linearizable". Es decir, si especifica el nivel de consistencia de lectura "linearizable" para db.collection.aggregate(), no puede incluir ninguna de las dos etapas en el pipeline.
La siguiente operación en un Set de réplicas especifica un nivel de consistencia de lectura de "majority" para leer la copia más reciente de los datos confirmados como están escritos en la mayoría de los nodos.
Importante
Puede especificar el nivel de consistencia de lectura
"majority"para una agregación que incluya una etapa$out.Independientemente del nivel de consistencia de lectura, es posible que los datos más recientes de un nodo no reflejen la versión más reciente de los datos en el sistema.
db.restaurants.aggregate( [ { $match: { rating: { $lt: 5 } } } ], { readConcern: { level: "majority" } } )
Para asegurarte de que un solo hilo pueda leer sus propias escrituras, utiliza el nivel de consistencia de lectura "majority" y el nivel de confirmación de escritura "majority" contra el primario del set de réplicas.
Usar variables en let
Nuevo en la versión 5.0.
Para definir variables a las que pueda acceder en otros lugares del comando, utilice la opción let.
Nota
Cree una colección cakeSales que contenga ventas de sabores de pastel:
db.cakeSales.insertMany( [ { _id: 1, flavor: "chocolate", salesTotal: 1580 }, { _id: 2, flavor: "strawberry", salesTotal: 4350 }, { _id: 3, flavor: "cherry", salesTotal: 2150 } ] )
El siguiente ejemplo:
recupera el pastel que tiene un
salesTotalmayor que 3000, que es el pastel con un_idde 2define una variable
targetTotalenlet, la cual se referencia en$gtcomo$$targetTotal
db.runCommand( { aggregate: db.cakeSales.getName(), pipeline: [ { $match: { $expr: { $gt: [ "$salesTotal", "$$targetTotal" ] } } }, ], cursor: {}, let: { targetTotal: 3000 } } )