/ /

aggregate (comando de base de datos)

Definición

aggregate: Realiza operaciones de agregación utilizando el pipeline de agregación. El pipeline 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 asistentes db.aggregate() y db.collection.aggregate() o con el método asistente watch().
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 5.0 versión.:

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

aggregate

string

El nombre de la colección o vista que sirve como entrada para el pipeline de agregación. Utilizar 1 para comandos independientes de la colección.

pipeline

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.

explain

booleano

Opcional. Especificar devolver la información sobre el procesamiento del pipeline.

No disponible en transacciones multi-documento.

allowDiskUse

booleano

Opcional.

Usa esta opción para anular allowDiskUseByDefault para una query específica. Puedes utilizar esta opción para lo siguiente:

Prohíbe el uso del disco en un sistema en que el uso del disco está permitido por defecto.
Permite el uso del disco en un sistema en que el uso del disco está prohibido por defecto.

A partir de MongoDB 6.0, si allowDiskUseByDefault está configurado en true y el servidor requiere más de 100 megabytes de memoria para una etapa de ejecución de pipeline, MongoDB guarda archivos temporales en el disco automáticamente, a menos que la query especifique { allowDiskUse: false }.

Para obtener más detalles, consulte allowDiskUseByDefault.

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.

cursor

Documento

Especificar un documento que contenga opciones que controlen la creación del objeto cursor.

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> }.

maxTimeMS

non-negative integer

Opcional.

Especifica un límite de tiempo en milisegundos. Si no especifica un valor para maxTimeMS, las operaciones no agotarán el tiempo de espera. Un valor de 0 especifica explícitamente el comportamiento por defecto sin límites.

MongoDB finaliza las operaciones que exceden su límite de tiempo asignado utilizando el mismo mecanismo que db.killOp(). MongoDB solo termina una operación en uno de sus puntos de interrupción designados.

bypassDocumentValidation

booleano

Opcional. Aplicable solo si se especifican las etapas de agregación $out o $merge.

Permite que omita la validación del esquema durante la operación. Esto permite insertar documentos que no cumplen con los requisitos de aggregate validación.

readConcern

Documento

Opcional. Especifica el nivel de consistencia de lectura.

La opción readConcern tiene la siguiente sintaxis: readConcern: { level: <value> }

Los posibles niveles de consistencia de lectura son estos:

"local"Este es el nivel de consistencia de lectura por defecto para las operaciones de lectura contra el primario y los secundarios.
"available". Disponible para operaciones de lectura en el primario y los secundarios. "available" se comporta de la misma manera que "local" contra el primario y los secundarios no particionados. La query devuelve los datos más recientes de la instancia.
"majority". Disponible para Sets de réplicas que utilizan el motor de almacenamiento WiredTiger.
"linearizable". Disponible solo para operaciones de lectura en primary.
"snapshot". Disponible para transacciones multi-documento y ciertas operaciones de lectura fuera de las transacciones multi-documento.

Para obtener más información sobre los niveles de consistencia de lectura, consulta Nivel de consistencia de lectura.

La etapa $out no se puede usar junto con el nivel de consistencia de lectura "linearizable". Si especificas "linearizable" nivel de consistencia de lectura para db.collection.aggregate(), no podrás incluir la etapa $out en la pipeline.

La etapa $merge no se puede usar junto con el nivel de consistencia de lectura "linearizable". Es decir, si especificas el "linearizable" nivel de consistencia de lectura para db.collection.aggregate(), no puedes incluir la etapa $merge en la pipeline.

collation

Documento

Opcional.

Opcional. Especifica la intercalación que se debe 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:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

Al especificar la intercalación, el campo locale es obligatorio; todos los demás campos de intercalación son opcionales. Para las descripciones de los campos, consulta Documento de intercalación.

Si no se especifica la intercalación, pero la colección tiene una intercalación por defecto (ver db.createCollection()), la operación utiliza la intercalación especificada para la colección.

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.

hint

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 hint no se aplica a las etapas $lookup y $graphLookup.

comment

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:

Mensajes de registro de mongod, en el campo attr.command.cursor.comment.
Salida del perfilador de base de datos, en el campo command.comment.
currentOp de salida, en el campo command.comment.

Un comentario puede ser de cualquier tipo BSON válido (string, objeto, arreglo, etc.).

Cualquier comentario establecido en un comando aggregate es heredado por cualquier comando getMore posterior que se ejecute en el cursor aggregate.

writeConcern

Documento

Opcional. Un documento que expresa el nivel de confirmación de escritura a utilizar con la etapa $out o $merge.

Omitir para usar el nivel de confirmación de escritura por defecto con la etapa $out o $merge.

let

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:

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

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 ($$) junto con el nombre de la variable en la forma $$<variable_name>. Por ejemplo: $$targetTotal.

Para usar una variable como filtro de resultados en una etapa de $match del pipeline, se debe acceder a la variable dentro del operador $expr.

Para un ejemplo completo usando let y variables, ve a Usa Variables en let.

Novedad 5.0 en la versión.:

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 getMore dentro de la transacción.
Para los cursores creados en una transacción, no puedes llamar a getMore fuera 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.

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 explain en un comando aggregate. Si se hace esto, el servidor devuelve un error APIStrictError.
Al utilizar la etapa $collStats, solo puede utilizar el campo count. No hay otros campos $collStats disponibles.

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 del pipeline que requieren más de 100 megabytes de memoria para ejecutarse escriben archivos temporales en el disco de forma predeterminada. Estos archivos temporales duran toda la ejecución del pipeline y pueden influir en el espacio de almacenamiento en la instancia. En versiones anteriores de MongoDB, se debe pasar { allowDiskUse: true } a los comandos individuales 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 cuando allowDiskUseByDefault se establece en false
Se utiliza { allowDiskUse: false } para prohibir la escritura de archivos temporales en el disco cuando allowDiskUseByDefault esté configurado en true

Tip

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`

Novedad 5.0 en la versión.:

Para definir variables a las que puedas acceder en otras partes del comando, utiliza la opción let.

Nota

Para filtrar resultados usando una variable en una etapa de la pipeline $match, debe acceder a la variable dentro del operador $expr.

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 salesTotal mayor que 3000, que es el pastel con un _id de 2
define una variable targetTotal en let, la cual se referencia en $gt como $$targetTotal

db.runCommand( {
   aggregate: db.cakeSales.getName(),
   pipeline: [
      { $match: {
           $expr: { $gt: [ "$salesTotal", "$$targetTotal" ] }
      } },
    ],
    cursor: {},
    let: { targetTotal: 3000 }
} )

Tip

db.collection.aggregate()

Volver

Comandos CRUD

bulkWrite

aggregate (comando de base de datos)

Definición

Tip

Compatibilidad

Importante

Sintaxis

Campos de comandos

Sesiones

Tiempo de espera de inactividad de la sesión

Transacciones

Importante

Desconexión del cliente

Stable API

Ejemplo

Agregación de datos con pipeline multi-etapas

Usar $currentOp en una base de datos admin

Nota

Información sobre la operación de agregación

Nota

La salida explicativa está sujeta a cambios entre versiones.

Tip

Interacción con allowDiskUseByDefault

Tip

Agregación de datos especificando el tamaño de agrupación

Especifica una intercalación

Sugerencia de índice

Anular el nivel de consistencia de lectura por defecto

Importante

Usar variables en let

Nota

Tip

Interacción con `allowDiskUseByDefault`

Usar variables en `let`