/ /

aggregate (comando de base de datos)

Definición

aggregate: Realiza una operación de agregación usando 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 puede ejecutarse 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 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

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 aggregate omita la validación de esquemas durante la operación. Esto permite insertar documentos que no cumplen con los requisitos de 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.

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:

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, vea Uso de variables en let.

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

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

Excepto por los dos primeros ejemplos que demuestran la sintaxis del comando, los ejemplos de esta página utilizan el asistente db.collection.aggregate().

Los ejemplos de esta página utilizan datos del conjunto de datos de muestra 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 se realizó alguna modificación en las bases de datos de muestra, es posible que se deban descartar y volver a crear las bases de datos para ejecutar los ejemplos de esta página.

Agregación de datos con pipeline multi-etapas

La colección movies en la base de datos sample_mflix contiene documentos como estos:

Nota

Los document en la colección movies contienen campos adicionales que no se muestran aquí.

{
   title: 'The Shawshank Redemption',
   year: 1994,
   genres: [ 'Crime', 'Drama' ],
   runtime: 142,
   imdb: { rating: 9.3, votes: 1521105, id: 111161 },
   directors: [ 'Frank Darabont' ],
   cast: [ 'Tim Robbins', 'Morgan Freeman', 'Bob Gunton', 'William Sadler' ],
},
{
   title: 'The Godfather',
   year: 1972,
   genres: [ 'Crime', 'Drama' ],
   runtime: 175,
   imdb: { rating: 9.2, votes: 1038358, id: 68646 },
   directors: [ 'Francis Ford Coppola' ],
   cast: [ 'Marlon Brando', 'Al Pacino', 'James Caan', 'Richard S. Castellano' ]
},
{
   title: 'Pulp Fiction',
   year: 1994,
   genres: [ 'Crime', 'Drama' ],
   runtime: 154,
   imdb: { rating: 8.9, votes: 1179033, id: 110912 },
   directors: [ 'Quentin Tarantino' ],
   cast: [ 'Tim Roth', 'Amanda Plummer', 'Laura Lovelace', 'John Travolta' ]
},
{
   title: 'Forrest Gump',
   year: 1994,
   genres: [ 'Drama', 'Romance' ],
   runtime: 142,
   imdb: { rating: 8.8, votes: 1087227, id: 109830 },
   directors: [ 'Robert Zemeckis' ],
   cast: [ 'Tom Hanks', 'Rebecca Williams', 'Sally Field', 'Michael Conner Humphreys' ],
},
{
   title: 'Inception',
   year: 2010,
   genres: [ 'Action', 'Sci-Fi', 'Thriller' ],
   runtime: 148,
   imdb: { rating: 8.8, votes: 1294646, id: 1375666 },
   directors: [ 'Christopher Nolan' ],
   cast: [ 'Leonardo DiCaprio', 'Joseph Gordon-Levitt', 'Ellen Page', 'Tom Hardy' ],
}

El siguiente ejemplo realiza una operación aggregate en la colección movies para calcular el recuento de cada género distinto que aparece en la colección.

db.runCommand( {
    aggregate: "movies", 
    pipeline: [
       { $project: { genres: 1 } },
       { $unwind: "$genres" },
       { $group: { _id: "$genres", count: { $sum : 1 } } }
    ],
    cursor: { }
} )

En mongosh, esta operación puede utilizar el asistente db.collection.aggregate() como se muestra en el siguiente ejemplo:

db.movies.aggregate( 
    [
       { $project: { genres: 1 } },
       { $unwind: "$genres" },
       { $group: { _id: "$genres", 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.comments.aggregate(
     [
        { $match: { date: { $gte: ISODate("2015-01-01") } } },
        { $group: { _id: "$movie_id", commentCount: { $sum: 1 } } },
        { $sort: { commentCount: -1 } }
     ],
     { explain: true }
)

Nota

La salida explicativa está sujeta a cambios entre versiones.

Interacción con `allowDiskUseByDefault`

Las etapas de la pipeline que requieren más de 100 megabytes de memoria para ejecutarse escriben archivos temporales en el disco por defecto. Estos archivos temporales duran durante la ejecución del pipeline y pueden afectar el espacio de almacenamiento en tu instancia.

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

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.theaters.aggregate( 
    [
       { $match: { "location.address.state": "NY" } },
       { $group: { _id: "$location.address.city", theaterCount: { $sum: 1 } } },
       { $sort: { theaterCount: -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.

La siguiente operación de agregación devuelve los títulos de todas las películas francesas en la colección movies de la base de datos sample_mflix y especifica la intercalación fr:

db.movies.aggregate(
    [ 
       { $match: {"countries": "France", "languages": "French"} }, 
       { $project: { "title": 1, "_id": 0 } }
    ],
    { collation: { locale: "fr", strength: 1 } }
)

Para obtener descripciones sobre los campos de intercalación, consulta el Documento de intercalación.

Sugerencia de índice

La colección movies en la base de datos sample_mflix contiene document similares a estos:

{
   title: "The Shawshank Redemption",
   year: 1994, rated: "R",
   imdb: { rating: 9.3, votes: 1513145, id: 111161 }
},
{
   title: "The Godfather",
   year: 1972,
   rated: "R",
   imdb: { rating: 9.2, votes: 1038358, id: 68646 }
},
{
   title: "The Dark Knight",
   year: 2008, rated: "PG-13",
   imdb: { rating: 9, votes: 1495351, id: 468569 }
},
{
   title: "Forrest Gump",
   year: 1994,
   rated: "PG-13",
   imdb: { rating: 8.8, votes: 1087227, id: 109830 }
}

Supongamos que existen los siguientes índices en la colección movies:

db.movies.createIndex( { "imdb.rating": 1, year: 1 } )

db.movies.createIndex( { "imdb.rating": 1, rated: 1 } )

La siguiente operación de agregación incluye la opción hint para forzar el uso del índice especificado:

db.movies.aggregate(
    [
        { $sort: { "imdb.rating": 1 } }, 
        { $match: { rated: "R", "imdb.rating": { $gte: 9.0 } } }, 
        { $sort: { year: -1 } } 
    ],
    { hint: { "imdb.rating": 1, rated: 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.

La siguiente operación en la colección movies de la base de datos sample_mflix especifica un nivel de consistencia de lectura de "majority" para leer la copia más reciente de los datos confirmados como 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.movies.aggregate(
    [ 
       { $match: { "imdb.rating": { $gte: 8.0 } } },
       { $group: { _id: "$rated", avgRating: { $avg: "$imdb.rating" }, count: { $sum: 1 } } },
       { $sort: { avgRating: -1 } }
    ],
    { 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`

Para definir variables a las que pueda acceder en otros lugares del comando, utilice 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.

La colección movies en la base de datos sample_mflix contiene document como este:

{
   title: "The Shawshank Redemption",
   year: 1994,
   rated: "R",
   imdb: { rating: 9.3, votes: 1513145, id: 111161 },
   runtime: 142
}

El siguiente ejemplo utiliza la opción let para definir variables que se pueden utilizar en la pipeline. Esta agregación encuentra películas con altas calificaciones y largas duraciones:

db.runCommand( {
    aggregate: "movies",
    pipeline: [
       { $match: {
            $expr: { 
               $and: [
                  { $gte: [ "$imdb.rating", "$$minRating" ] },
                  { $gte: [ "$runtime", "$$minRuntime" ] }
               ]
            }
       } },
       { $project: { 
            title: 1, 
            year: 1, 
            "imdb.rating": 1, 
            runtime: 1 
       } },
       { $sort: { "imdb.rating": -1 } },
       { $limit: 3 }
     ],
     cursor: {},
     let: { minRating: 8.5, minRuntime: 120 }
} )

Obtén más información

Volver

Comandos CRUD

bulkWrite

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

Configuración de query

Stable API

Ejemplo

Agregación de datos con pipeline multi-etapas

Nota

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.

Interacción con allowDiskUseByDefault

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

Obtén más información

Interacción con `allowDiskUseByDefault`

Usar variables en `let`