/ /

$merge (etapa de agregación)

Definición

Nota

Esta página describe el $merge etapa, que arroja los resultados del pipeline de agregación en una colección. Para el El operador $mergeObjects, que fusiona documentos en un solo documento, consulta $mergeObjects.

$merge

Escribe los resultados de la canalización de agregación en una colección especificada. El operador $merge debe ser la última etapa del pipeline.

La etapa $merge:

Se puede enviar a una colección en la misma base de datos o en una base de datos diferente.
Puede generar salida a la misma colección que se está agregando. Para más información, consulte Salida a la misma colección que se está agregando
Considera los siguientes puntos al usar las etapas $merge o $out en un pipeline de agregación:
- A partir de MongoDB 5.0, los pipelines con una etapa $merge pueden ejecutarse en nodos secundarios del set de réplicas si todos los nodos del clúster tienen la featureCompatibilityVersion establecida en 5.0 o superior y la preferencia de lectura permite lecturas secundarias.
  - $merge y $out se ejecutan en nodos secundarios, pero las operaciones de escritura se envían al nodo primario.
  - No todas las versiones de los drivers son compatibles con las operaciones $merge enviadas a los nodos secundarios. Para obtener más detalles, consulte la documentación del driver.
- En versiones anteriores de MongoDB, los pipelines con etapas de $out o $merge siempre se ejecutan en el nodo primario y no se considera la preferencia de lectura.
Cree una nueva colección si la colección de salida no existe ya.
Puede incorporar resultados (insertar nuevos documentos, fusionar documentos, reemplazar documentos, mantener documentos existentes, fallar la operación, procesar documentos con un pipeline de actualización personalizado) en una colección existente.
Puede dar salida a una colección fragmentada. La colección de entrada también se puede fragmentar.

Para una comparación con la etapa $out que también genera los resultados de la agregación en una colección, consulta Comparación de $merge y $out.

Nota

Vistas materializadas on-demand

$merge puede incorporar los resultados del pipeline en una colección de salida existente en lugar de realizar un reemplazo completo de la colección. Esta funcionalidad permite a los usuarios crear vistas materializadas on-demand, donde el contenido de la colección de salida se actualiza de forma incremental cuando se ejecuta el pipeline.

Para obtener más información sobre este caso de uso, consulta Vistas materializadas on-demand así como los ejemplos de esta página.

Las vistas materializadas son distintas de las vistas de solo lectura. Para obtener información sobre la creación de vistas de solo lectura, consulta vistas de solo lectura.

Compatibilidad

Puedes usar $merge para implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

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

$merge tiene la siguiente sintaxis:

{ $merge: {
     into: <collection> -or- { db: <db>, coll: <collection> },
     on: <identifier field> -or- [ <identifier field1>, ...],  // Optional
     let: <variables>,                                         // Optional
     whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
     whenNotMatched: <insert|discard|fail>                     // Optional
} }

Por ejemplo:

{ $merge: { into: "myOutput", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } }

Si utilizas todas las opciones por defecto para $merge, incluida la escritura en una colección de la misma base de datos, puedes utilizar la forma simplificada:

{ $merge: <collection> } // Output collection is in the same database

La etapa $merge procesa un documento con los siguientes campos:

Campo

Descripción

La colección de resultados. Especifica una de las siguientes opciones:

El nombre de la colección como un string para enviar a una colección en la misma base de datos donde se ejecuta la agregación. Por ejemplo:
into: "myOutput"
El nombre de la base de datos y de la colección en un documento para enviar a una colección en la base de datos especificada. Por ejemplo:
into: { db:"myDB", coll:"myOutput" }

Si la colección de salida no existe, $merge crea la colección:

Para un Set de réplicas o un autónomo, si la base de datos de salida no existe, $merge también crea la base de datos.
Para un clúster particionado, la base de datos de salida especificada ya debe existir.

La colección de salida puede ser una colección fragmentada.

Opcional. Campo o campos que funcionan como identificador único de un documento. El identificador determina si un documento de resultados coincide con un documento existente en la colección de salida. Especifique uno de los siguientes:

Un solo nombre de campo como un string. Por ejemplo:
on: "_id"
Una combinación de campos en un arreglo. Por ejemplo:
on: [ "date", "customerId" ]
The order of the fields in the array does not matter, and you cannot specify the same field multiple times.

Para el campo o los campos especificados:

Los documentos de resultados de la agregación deben contener el(los) campo(s) especificado(s) en el on, a menos que el campo on sea el campo _id. Si falta el campo _id en un documento de resultados, MongoDB lo agrega automáticamente.
Para las implementaciones que ejecutan MongoDB 8.0 y versiones anteriores, los campos especificados para on no pueden faltar ni contener un valor nulo. A partir de MongoDB 8.1, si el índice de soporte no es disperso, el campo o los campos especificados para on pueden faltar o contener un valor nulo.
El campo o los campos especificados no pueden contener un valor de arreglo.

$merge requiere un índice único con claves que correspondan a los campos de identificador on. Aunque el orden de la especificación de la clave del índice no importa, el índice único debe contener únicamente los campos on como sus claves.

El índice también debe tener la misma intercalación que la de la agregación.
El índice único puede ser un índice disperso.
El índice único no puede ser un índice parcial.
Para las colecciones de salida que ya existen, el índice correspondiente ya debe existir.

El valor por defecto de on depende de la colección de salida:

Si la colección de salida no existe, el identificador on debe ser y por defecto es el campo _id. El índice único correspondiente de _id se crea automáticamente.
- Para usar un campo(s) de identificador diferente on para una colección que no existe, primero puedes crear la colección creando un índice único en el(los) campo(s) deseado(s). Consulta la sección sobre la colección de salida inexistente para un ejemplo.
- A partir de MongoDB 8.3, el servidor verifica que el índice _id creado automáticamente coincida con la intercalación de la query. Si las intercalaciones no coinciden, el _id índice no puede proporcionar unicidad a la query, y la query no se ejecutará.
Si la colección de salida existente no está particionada, el identificador on se asigna por defecto al campo _id.
Si la colección de salida existente es una colección fragmentada, el identificador on se asigna por defecto a todos los campos de la clave de fragmentación y al campo _id. Si se especifica un identificador de on diferente, el on debe contener todos los campos de la clave de fragmentación.

whenMatched

Opcional. El comportamiento de $merge si un documento resultante y un documento existente en la colección tienen el mismo valor para el o los campos on especificados.

Se puede especificar cualquiera de los dos:

Una de las cadenas de acción predefinidas:

Acción	Descripción
“reemplazar”	Reemplaza el documento existente en la colección de salida con el documento de resultados coincidente. Al realizar una sustitución, el documento de reemplazo no puede dar lugar a una modificación del valor `_id` o, si la colección de salida está particionada, del valor de la clave de partición. De lo contrario, la operación genera un error. Para evitar este error, si el campo on no incluye el campo `_id`, remueve el campo `_id` en los resultados de la agregación para evitar el error, como con una etapa `$unset` anterior, y así sucesivamente.
"mantenerExistente"	Mantén el documento existente en la colección de salida.
"merge" (por defecto)	Fusionar los documentos coincidentes (similar al operador `$mergeObjects`). Si el documento de resultados contiene campos que no están en el documento existente, se deben agregar estos nuevos campos al documento existente. Si el documento de resultados contiene campos en el documento existente, se deben reemplazar los valores de los campos existentes con los del documento de resultados. Por ejemplo, si la colección de salida contiene el documento: `{ _id: 1, a: 1, b: 1 }` Y los resultados de la agregación contienen el documento: `{ _id: 1, b: 5, z: 1 }` Entonces, el documento combinado es: `{ _id: 1, a: 1, b: 5, z: 1 }` Al realizar una fusión, el documento fusionado no puede resultar en una modificación del valor de `_id` ni, si la colección de salida está particionada, del valor de la clave de partición. De lo contrario, la operación genera un error. Para evitar este error, si el campo on no incluye el campo `_id`, remueve el campo `_id` en los resultados de la agregación para evitar el error, como con una etapa `$unset` anterior, y así sucesivamente.
“error”	Se debe detener y cancelar la operación de agregación. Cualquier cambio en la colección de salida de documentos anteriores no se revierte.

Un pipeline de agregación para actualizar el documento en la colección.
[ <stage1>, <stage2> ... ]
El pipeline solo puede consistir en las siguientes etapas:
- $addFields y su alias $set
- $project y su alias $unset
- $replaceRoot y su alias $replaceWith
El pipeline no puede modificar el valor del campo on. Por ejemplo, si estás haciendo coincidir en el campo month, el pipeline no puede modificar el campo month.
El pipeline whenMatched puede acceder directamente a los campos de los documentos existentes en la colección de salida usando $<field>.
Para acceder a los campos de los documentos de resultados de agregación, usa cualquiera de las siguientes opciones:
- La variable $$new de funcionalidad incorporada para acceder al campo. Específicamente, $$new.<field>. La variable $$new solo está disponible si se omite la especificación let.
- Las variables definidas por el usuario en el campo let.
  Se debe especificar el prefijo del signo de dólar doble ($$) junto con el nombre de la variable en el formato $$<variable_name>. Por ejemplo, $$year. Si la variable está configurada como un documento, también se puede incluir un campo de documento en el formulario $$<variable_name>.<field>. Por ejemplo, $$year.month.
  Para más ejemplos, consulta Usar variables para personalizar la combinación.

permitir

Opcional. Especifica variables para uso en el pipeline whenMatched.

Especifica un documento con los nombres de las variables y las expresiones de valores:

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

Si no se especifica, es por defecto { new: "$$ROOT" } (consulta ROOT). El pipeline whenMatched puede acceder a la variable $$new.

Para acceder a las variables en el pipeline whenMatched:

Se debe especificar el prefijo del signo de dólar doble ($$) junto con el nombre de la variable en el formato $$<variable_name>. Por ejemplo, $$year. Si la variable está configurada como un documento, también se puede incluir un campo de documento en el formulario $$<variable_name>.<field>. Por ejemplo, $$year.month.

Para ejemplos, consulta Usar Variables para personalizar la combinación.

whenNotMatched

Opcional. El comportamiento de $merge si un documento de resultado no coincide con un documento existente en la colección de salida.

Puedes especificar una de las cadenas de acción predefinidas:

Acción	Descripción
"insert" (Default)	Inserta el documento en la colección de salida.
"descartar"	Desecha el documento. Específicamente, `$merge` no inserta el documento en la colección de salida.
“error”	Se debe detener y cancelar la operación de agregación. Cualquier cambio ya escrito en la colección de salida no se revierte.

Considerations

`_id` Generación de campos

Si el campo _id no está presente en un documento de los resultados de la pipeline de agregación, la etapa $merge lo genera automáticamente.

Por ejemplo, en la siguiente pipeline de agregación, $project excluye el campo _id de los documentos pasados a $merge. Cuando $merge guarda estos documentos en el "newCollection", $merge genera un nuevo campo _id y un valor.

db.movies.aggregate( [
   { $project: { _id: 0 } },
   { $merge : { into : "newCollection" } }
] )

Crear una nueva colección si la colección de salida no existe

La operación $merge crea una nueva colección si la colección de salida especificada no existe.

La colección de salida se crea cuando $merge guarda el primer documento a la colección y es visible inmediatamente.
Si la agregación falla, cualquier guardado completado por el $merge antes del error no se revertirá.

Nota

Para un Set de réplicas o un autónomo, si la base de datos de salida no existe, $merge también crea la base de datos.

Para un clúster particionado, la base de datos de salida especificada ya debe existir.

Si la colección de salida no existe, $merge requiere que el identificador on sea el campo _id. Para utilizar un valor de campo on diferente para una colección que no existe, primero puedes crear la colección creando un índice único en el(los) campo(s) deseado(s). Por ejemplo, si la colección de salida newDailyCommentCount no existe y deseas especificar el campo commentDate como el identificador on:

db.newDailyCommentCount.createIndex(
   { commentDate: 1 }, { unique: true } )
db.comments.aggregate( [
   { $match: { date: { $gte: new Date("2002-01-01"),
     $lt: new Date("2002-02-01") } } },
   { $group: { _id: { $dateToString: { format: "%Y-%m-%d",
     date: "$date" } }, count: { $sum: 1 } } },
   { $project: { _id: 0, commentDate: { $toDate: "$_id" },
     count: 1 } },
   { $merge : { into : "newDailyCommentCount",
     on: "commentDate" } }
] )

Salida a una colección fragmentada

La etapa $merge puede generar una salida a una colección fragmentada. Cuando la colección de salida está particionada, $merge usa el campo _id y todos los campos de clave de partición como el identificador por defecto. Si anulas el valor por defecto, el identificador en debe incluir todos los campos de la clave de partición:

{ $merge: {
   into: "<shardedColl>" or { db:"<sharding enabled db>", coll: "<shardedColl>" },
   on: [ "<shardkeyfield1>", "<shardkeyfield2>",... ], // Shard key fields and any additional fields
   let: <variables>,                                         // Optional
   whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
   whenNotMatched: <insert|discard|fail>                     // Optional
} }

Por ejemplo, se debe usar el método sh.shardCollection() para crear una nueva colección particionada moviesByYearAndRating con el campo rated como clave de partición.

sh.shardCollection(
   "sample_mflix.moviesByYearAndRating",  // Namespace of the collection to shard
   { rated: 1 },                       // Shard key
);

La colección moviesByYearAndRating contendrá documentos con estadísticas de películas por año (campo year) y clasificación de contenido (clave de partición); específicamente, el identificador en es ["year", "rated"] (el orden de los campos no importa). Debido a que $merge requiere un índice único con claves que correspondan a los campos de identificador en, crea el índice único (el orden de los campos no importa): [1]

db.moviesByYearAndRating.createIndex(
   { rated: 1, year: 1 }, { unique: true } )

Con la colección particionada moviesByYearAndRating y el índice único creado, se puede utilizar $merge para enviar los resultados de la agregación a esta colección, coincidiendo en [ "year", "rated" ] como en este ejemplo:

db.movies.aggregate( [
   { $match: { rated: { $ne: null }, year: { $ne: null } } },
   { $group: {
      _id: { year: "$year", rated: "$rated" },
      movieCount: { $sum: 1 } } },
   { $project: { _id: 0, year: "$_id.year", rated: "$_id.rated",
     movieCount: 1 } },
   { $merge: { into: "moviesByYearAndRating",
     "on": [ "year", "rated" ], whenMatched: "replace",
     whenNotMatched: "insert" } }
] )

[1] El método sh.shardCollection() también puede crear un índice único en la clave de fragmentación cuando se pasa la opción { unique: true } si: la clave de fragmentación es basada en rango, la colección está vacía y no existe un índice único en la clave de fragmentación. En el ejemplo anterior, dado que el identificador on es la clave de fragmentación y otro campo, se requiere una operación separada para crear el índice correspondiente.

Reemplazar documentos (`$merge`) frente a Reemplazar colección (`$out`)

$merge puede reemplazar un documento existente en la colección de resultados si los resultados de la agregación contienen uno o varios documentos que coinciden según la especificación. Por lo tanto, $merge puede reemplazar todos los documentos en la colección existente si los resultados de la agregación incluyen documentos coincidentes para todos los documentos existentes en la colección y especificar "reemplazar" para whenMatched.

Sin embargo, para reemplazar una colección existente independientemente de los resultados de la agregación, se debe usar $out en su lugar.

Documentos existentes y `_id` y valores de la clave de partición

Los $merge errores ocurren si el $merge resulta en un cambio en el valor _id de un documento existente.

Tip

Para evitar este error, si el campo on no incluye el campo _id, remueve el campo _id en los resultados de la agregación para evitar el error, como con una etapa $unset precedente, y así sucesivamente.

Además, para una colección fragmentada, $merge también genera un error si provoca un cambio en el valor de clave de fragmentación de un documento existente.

Cualquier guardado completado por el $merge antes del error no se revertirá.

Restricciones de índice único

Si el índice único utilizado por $merge para los campo(s) se descartan a mitad de la agregación, no hay garantía de que la agregación se detenga. Si la agregación continúa, no hay garantía de que los documentos no tengan valores duplicados en el campo on.

Si el $merge intenta guardar un documento que viola algún índice único en la colección de salida, la operación genera un error. Por ejemplo:

Insertar un documento no coincidente que viola un índice único distinto del índice en el campo(s).
Falla si hay un documento coincidente en la colección. Específicamente, la operación intenta insertar el documento coincidente que infringe el índice único en el(los) campo(s) en.
Reemplaza un documento existente por un nuevo documento que infrinja un índice único distinto al índice en el(los) campo(s) on.
Fusionar los documentos coincidentes que resultan en un documento que viola un índice único distinto del índice en el en campo(s).

Validación de esquema

Si su colección utiliza validación de esquemas y tiene validationAction configurado en error, insertar un documento no válido o actualizar un documento con valores no válidos con $merge genera un MongoServerError y el documento no se escribe en la colección de destino. Si hay varios documentos no válidos, solo el primer documento no válido que se encuentre generará un error. Todos los documentos válidos se guardan en la colección de destino, y todos los documentos no válidos fallan al intentar guardarse.

`whenMatched` Comportamiento del pipeline

$merge inserta el documento directamente en la colección de salida cuando se cumplen todas las condiciones siguientes:

El valor de whenMatched es una pipeline de agregación.
El valor de whenNotMatched es insert.
No hay coincidencia para un documento en la colección de salida.

`$merge` y `$out` Comparación

Con la introducción de $merge, MongoDB proporciona dos etapas, $merge y $out, para escribir los resultados de la pipeline de agregación en una colección:

`$merge`	`$out`
Se puede enviar a una colección en la misma base de datos o en una base de datos diferente.	Se puede enviar a una colección en la misma base de datos o en una base de datos diferente.
Cree una nueva colección si la colección de salida no existe ya.	Cree una nueva colección si la colección de salida no existe ya.
Puede incorporar resultados (insertar nuevos documentos, fusionar documentos, reemplazar documentos, mantener documentos existentes, fallar la operación, procesar documentos con un pipeline de actualización personalizado) en una colección existente. See also Replace Documents (`$merge`) vs Replace Collection (`$out`).	Se debe reemplazar por completo la colección de salida si ya existe.
Puede dar salida a una colección fragmentada. La colección de entrada también se puede fragmentar.	No se puede enviar a una colección particionada. Sin embargo, la colección de entrada se puede particionar.
Corresponde a las instrucciones SQL: `MERGE`. `INSERT INTO T2 SELECT FROM T1`. `SELECT INTO T2 FROM T1`. Crear/actualizar vistas materializadas.	Corresponde a la instrucción SQL: `INSERT INTO T2 SELECT FROM T1`. `SELECT INTO T2 FROM T1`.

Salida a la misma colección que está siendo agregada

Advertencia

Cuando $merge guarda los resultados en la misma colección que se está agregando, los documentos pueden actualizarse varias veces o la operación puede resultar en un bucle infinito. Este comportamiento ocurre cuando la actualización realizada por $merge cambia la ubicación física de los documentos almacenados en el disco. Cuando la ubicación física de un documento cambia, $merge puede considerarlo como un documento completamente nuevo, lo que resulta en actualizaciones adicionales. Para más información sobre este comportamiento, consulte Problema de Halloween.

$merge puede generar salida a la misma colección que se está agregando. También puedes exportar a una colección que aparezca en otras etapas del pipeline, como $lookup.

Restricciones

Restricciones	Descripción
Transacciones	La pipeline de agregación no puede usar `$merge` dentro de una transacción.
Colecciones de series de tiempo	Un pipeline de agregación no puede usar `$merge` para generar una colección de series de tiempo.
view definition Separate from materialized view	Una definición de vista no puede incluir la etapa `$merge`. Si la definición de la vista incluye una pipeline anidada (por ejemplo, la definición de la vista incluye la etapa `$facet`), esta restricción de la etapa `$merge` también se aplica a las pipelines anidadas.
`$lookup` etapa	El pipeline anidado de la etapa `$lookup` no puede incluir la etapa `$merge`.
`$facet` etapa	El pipeline anidado de la etapa `$facet` no puede incluir la etapa `$merge`.
`$unionWith` etapa	El pipeline anidado de la etapa `$unionWith` no puede incluir la etapa `$merge`.
`"linearizable"` readConcern	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.

Ejemplos

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.

Vista materializada on-demand: creación inicial

Si la colección de salida no existe, el $merge crea la colección.

Nota

Para un set de réplicas o una implementación autónoma, si la base de datos de salida no existe, $merge también crea la base de datos.

Para una implementación de clúster particionado, la base de datos de salida especificada ya debe existir.

Puedes usar las etapas $group y $merge para crear una colección movieRatingSummary que resuma películas aclamadas por la crítica por año de lanzamiento y clasificación de contenido:

db.movies.aggregate( [
   { $match: { metacritic: 100, rated: { $ne: null },
     year: { $lte: 1972 } } },
   { $group: { _id: { year: "$year", rated: "$rated" },
     count: { $sum: 1 } } },
   { $merge : { into: "movieRatingSummary", on: "_id",
     whenMatched: "replace", whenNotMatched: "insert" } }
] )

El pipeline utiliza las siguientes etapas:

$match escenario para filtrar películas aclamadas por la crítica y estrenadas a través de 1972 con clasificación de contenido
$group etapa para agrupar las películas por year y rated
$merge etapa para guardar la salida de la etapa anterior $group en la colección movieRatingSummary de la base de datos sample_mflix

Para ver los documentos en la nueva colección movieRatingSummary:

db.movieRatingSummary.find().sort(
   { _id: 1 } )

[
  { _id: { year: 1939, rated: 'PASSED' }, count: 1 },
  { _id: { year: 1962, rated: 'PG' }, count: 1 },
  { _id: { year: 1963, rated: 'PG' }, count: 1 },
  { _id: { year: 1970, rated: 'R' }, count: 1 },
  { _id: { year: 1972, rated: 'R' }, count: 1 }
]

Tip

Vistas materializadas on-demand

Vista materializada on-demand: actualizar/reemplazar datos

Para actualizar la colección movieRatingSummary del ejemplo anterior y así incluir películas aclamadas por la crítica desde 1963 en adelante, esta pipeline de agregación utiliza las siguientes etapas:

$match Etapa para encontrar todas las películas con metacritic: 100, una clasificación de contenido y un año de lanzamiento mayor o igual a 1963.
Etapa $group para agrupar las películas por year y rated.
$merge para guardar el conjunto de resultados en la colección movieRatingSummary, reemplazando los documentos con el mismo valor _id. Para los documentos que no tienen coincidencias en la colección, $merge inserta los nuevos documentos.

db.movies.aggregate( [
   { $match: { metacritic: 100, rated: { $ne: null },
     year: { $gte: 1963 } } },
   { $group: { _id: { year: "$year", rated: "$rated" },
     count: { $sum: 1 } } },
   { $merge : { into: "movieRatingSummary", on: "_id",
     whenMatched: "replace", whenNotMatched: "insert" } }
] )

Después de ejecutar la agregación, visualiza los documentos en la colección movieRatingSummary:

db.movieRatingSummary.find().sort(
   { _id: 1 } )

[
  { _id: { year: 1939, rated: 'PASSED' }, count: 1 },
  { _id: { year: 1962, rated: 'PG' }, count: 1 },
  { _id: { year: 1963, rated: 'PG' }, count: 1 },
  { _id: { year: 1970, rated: 'R' }, count: 1 },
  { _id: { year: 1972, rated: 'R' }, count: 1 },
  { _id: { year: 1982, rated: 'R' }, count: 1 },
  { _id: { year: 2014, rated: 'R' }, count: 1 }
]

Tip

Vistas materializadas on-demand

Solo insertar datos nuevos

Para asegurar que el $merge no sobrescriba datos existentes en la colección, configura whenMatched a keepExisting o fail.

Una colección movieArchive en la base de datos sample_mflix contiene registros históricos de películas aclamadas por la crítica por año de estreno.

La colección movieArchive tiene un índice único en el campo year. Debe existir como máximo un registro por año de lanzamiento:

db.movieArchive.createIndex(
   { year: 1 }, { unique: true } )

Este pipeline de agregación actualiza la colección movieArchive con datos de la colección movies para incluir películas aclamadas por la crítica desde 1963 en adelante. El pipeline utiliza las siguientes etapas:

$match Etapa para encontrar todas las películas con metacritic: 100, una clasificación de contenido y year >= 1963.
$group etapa para agrupar los títulos de las películas por year.
La etapa $project para suprimir el campo _id y promover year a un campo de primer nivel. Cuando los documentos se pasan a $merge, $merge genera automáticamente un nuevo campo _id para los documentos.
$merge para guardar el conjunto de resultados en movieArchive.
La etapa $merge coincide los documentos en el campo year y falla cuando coincide. Es decir, si ya existe un documento para ese año de publicación, se producen los errores $merge.

db.movies.aggregate( [
   { $match: { metacritic: 100, rated: { $ne: null },
     year: { $gte: 1963 } } },
   { $group: { _id: "$year",
     titles: { $push: "$title" } } },
   { $project: { _id: 0, year: "$_id", titles: 1 } },
   { $merge : { into: "movieArchive", on: "year",
     whenMatched: "fail" } }
] )

Si la colección movieArchive ya contiene un documento para cualquier año en el rango 1963–2014, la agregación falla debido al error de clave duplicada. Sin embargo, el pipeline no revierte ningún documento que haya insertado antes del error.

Si especificas keepExisting para el documento coincidente, la agregación no afecta al documento coincidente y no genera un error de clave duplicada. De manera similar, si especificas reemplazar, la operación no falla; sin embargo, la operación reemplaza el documento existente.

Combinar resultados de múltiples colecciones

Por defecto, si un documento en los resultados de la agregación coincide con un documento en la colección, la etapa $merge fusiona los documentos.

Puedes utilizar $merge para fusionar los resultados de la colección movies y la colección comments para crear una nueva colección yearlyStats.

Para crear la colección yearlyStats, ejecuta la siguiente pipeline:

db.movies.aggregate( [
   { $match: { metacritic: 100, rated: { $ne: null },
     year: { $gte: 1970, $lte: 1972 } } },
   { $group: { _id: "$year", movieCount: { $sum: 1 } } },
   { $merge : { into: "yearlyStats", on: "_id",
     whenMatched: "merge", whenNotMatched: "insert" } }
])

Primera etapa:: La etapa $match filtra películas aclamadas por la crítica (metacritic: 100) con una clasificación de contenido, estrenadas entre 1970 y 1972.
Segunda fase:: La $group etapa agrupa por year y cuenta películas en un nuevo campo movieCount.
Tercera etapa:: La etapa $merge escribe los documentos en la colección yearlyStats en la misma base de datos. Si la etapa encuentra un documento existente en la colección que coincide en el campo _id, la etapa fusiona los documentos coincidentes. De lo contrario, la etapa inserta el documento. Para la creación inicial, ningún documento coincide.

Para ver los documentos en la colección, ejecute la siguiente operación:

db.yearlyStats.find().sort( { _id: 1 } )

[
  { _id: 1970, movieCount: 1 },
  { _id: 1972, movieCount: 1 }
]

De manera similar, se debe ejecutar la siguiente pipeline de agregación contra la colección comments para fusionar los conteos de comentarios en la colección yearlyStats.

db.comments.aggregate( [
   { $match: { date: { $gte: new Date("1970-01-01"),
     $lt: new Date("1973-01-01") } } },
   { $group: { _id: { $year: "$date" },
     commentCount: { $sum: 1 } } },
   { $merge : { into: "yearlyStats", on: "_id",
     whenMatched: "merge", whenNotMatched: "insert" } }
])

Primera etapa:: La etapa $match de filtro para los comentarios publicados entre 1970 y 1972.
Segunda fase:: La etapa $group agrupa por el año extraído del comentario date y cuenta los comentarios en un nuevo campo commentCount.
Tercera etapa:: La etapa $merge guarda los documentos en la colección yearlyStats en la misma base de datos. Si la etapa encuentra un documento existente en la colección que coincide con el campo _id (el año), la etapa fusiona los documentos coincidentes. De lo contrario, la etapa inserta el documento.

Para ver los documentos en la colección yearlyStats después de que los datos se hayan fusionado, ejecute la siguiente operación:

db.yearlyStats.find().sort( { _id: 1 } )

[
  { _id: 1970, movieCount: 1, commentCount: 889 },
  { _id: 1971, commentCount: 825 },
  { _id: 1972, movieCount: 1, commentCount: 863 }
]

Usar el pipeline para personalizar la fusión

El $merge puede usar un pipeline de actualización personalizada cuando los documentos coinciden. El pipeline whenMatched puede tener las siguientes etapas:

$addFields y su alias $set
$project y su alias $unset
$replaceRoot y su alias $replaceWith

Una colección monthlyCommentTotals rastrea el recuento acumulado de comentarios para cada mes.

Cada día llegan comentarios nuevos a la colección sample_mflix.comments. La siguiente pipeline de agregación actualiza el total mensual con el recuento de comentarios de ese día:

db.comments.aggregate([
   { $match: { date: { $gte: new Date("1970-01-15"),
     $lt: new Date("1970-01-16") } } },
   { $group: { _id: { $dateToString: { format: "%Y-%m",
     date: "$date" } }, count: { $sum: 1 } } },
   { $merge: {
         into: "monthlyCommentTotals",
         on: "_id",
         whenMatched: [
            { $addFields: {
               count: { $add: [ "$count", "$$new.count" ] }
            } }
         ],
         whenNotMatched: "insert"
   } }
])

Primera etapa:

La etapa $match encuentra todos los comentarios publicados el 15 de enero, 1970.

Segunda fase:

La fase $group agrupa los comentarios coincidentes por año-mes y los cuenta.

Tercera etapa:

La etapa $merge escribe los documentos para la colección monthlyCommentTotals. Si la etapa encuentra un documento existente en la colección que coincide con el campo _id, la etapa utiliza un pipeline para añadir el count del día al total mensual existente.

Este pipeline no puede acceder directamente a los campos del documento de resultados. Para acceder al campo count en el documento de resultados, la pipeline utiliza la variable $$new; es decir, $$new.count.
Esta pipeline puede acceder directamente al campo count del documento existente en la colección; es decir, $count.

El documento resultante sustituye al documento existente.

Para ver los documentos en la colección monthlyCommentTotals después de la operación de fusión, ejecute la siguiente operación:

db.monthlyCommentTotals.find()

[ { _id: '1970-01', count: 71 } ]

Usa variables para personalizar la fusión

Puedes utilizar variables en la etapa $merge en el campo whenMatched. Es necesario definir las variables antes de poder utilizarlas.

Defina variables en uno o en ambos de los siguientes:

$merge etapa let
El comandoaggregate let (a partir de MongoDB 5.0)

Para usar variables en whenMatched:

Las pestañas a continuación demuestran el comportamiento cuando las variables se definen en la etapa de fusión, el comando de agregación, o en ambos.

Utiliza las variables definidas en la etapa de combinación

Puedes definir variables en la etapa $merge let y usar las variables en el campo whenMatched.

El siguiente ejemplo:

inicializa la colección movieDetails con una película de la colección movies
ejecuta un comando que define aggregate una year variable en el $merge let y añade el año a movieDetails usando whenMatched
retrieves the movieDetails document

db.movies.aggregate( [
   { $match: { title: "The Godfather" } },
   { $limit: 1 },
   { $project: { title: 1 } },
   { $merge: { into: "movieDetails", whenNotMatched: "insert" } }
] )
db.runCommand( {
   aggregate: db.movieDetails.getName(),
   pipeline: [ {
      $merge: {
         into: db.movieDetails.getName(),
         let : { year: "2023" },
         whenMatched: [ {
            $addFields: { "addedYear": "$$year" }
         } ]
      }
   } ],
   cursor: {}
} )
db.movieDetails.find()

[ { _id: ..., title: 'The Godfather', addedYear: '2023' } ]

Utilice las variables definidas en el comando Aggregate

Nuevo en la versión 5.0.

Puedes definir variables en el comando aggregate let y usar las variables en la etapa $merge campo whenMatched.

El siguiente ejemplo:

inicializa la colección movieDetails con una película de la colección movies
ejecuta un comando aggregate que define una variable year en el comando aggregate let y añade el año a movieDetails usando whenMatched
retrieves the movieDetails document

db.movies.aggregate( [
   { $match: { title: "The Godfather" } },
   { $limit: 1 },
   { $project: { title: 1 } },
   { $merge: { into: "movieDetails", whenNotMatched: "insert" } }
] )
db.runCommand( {
   aggregate: db.movieDetails.getName(),
   pipeline: [ {
      $merge: {
         into: db.movieDetails.getName(),
         whenMatched: [ {
            $addFields: { "addedYear": "$$year" }
         } ]
      }
   } ],
   cursor: {},
   let : { year: "2023" }
} )
db.movieDetails.find()

[ { _id: ..., title: 'The Godfather', addedYear: '2023' } ]

Utilice variables definidas en la etapa de combinación y en el comando de agregación

Puede definir variables en la etapa $merge y, a partir de MongoDB 5.0, el comando aggregate.

Si se definen dos variables con el mismo nombre en la etapa $merge y el comando aggregate, se utiliza la variable de etapa $merge.

En este ejemplo, la pipeline utiliza year: "2023" en vez de la variable de comando year: "2019" aggregate:

db.movies.aggregate( [
   { $match: { title: "The Godfather" } },
   { $limit: 1 },
   { $project: { title: 1 } },
   { $merge: { into: "movieDetails", whenNotMatched: "insert" } }
] )
db.runCommand( {
   aggregate: db.movieDetails.getName(),
   pipeline: [ {
      $merge: {
         into: db.movieDetails.getName(),
         let : { year: "2023" },
         whenMatched: [ {
            $addFields: { "addedYear": "$$year" }
         } ]
      }
   } ],
   cursor: {},
   let : { year: "2019" }
} )
db.movieDetails.find()

[ { _id: ..., title: 'The Godfather', addedYear: '2023' } ]

La siguiente clase Movie modela los documentos utilizados en este ejemplo:

[BsonIgnoreExtraElements]
public class Movie
{
    [BsonId]
    public ObjectId Id { get; set; }
    [BsonElement("title")]
    public string Title { get; set; } = null!;
    [BsonElement("year")]
    public int? Year { get; set; }
    [BsonElement("runtime")]
    public int? Runtime { get; set; }
    [BsonElement("rated")]
    public string? Rated { get; set; }
    [BsonElement("metacritic")]
    public int Metacritic { get; set; }
    [BsonElement("plot")]
    public string? Plot { get; set; }
    [BsonElement("type")]
    public string? Type { get; set; }
    [BsonElement("cast")]
    public string[]? Cast { get; set; }
    [BsonElement("directors")]
    public string[]? Directors { get; set; }
    [BsonElement("writers")]
    public string[]? Writers { get; set; }
    [BsonElement("imdb")]
    public ImdbData? Imdb { get; set; }
}

Para usar el driver de MongoDB .NET/C# para agregar una etapa $merge a un pipeline de agregación, llama al método Merge() en un objeto PipelineDefinition.

Cuando se llame al método Merge(), se debe pasar una instancia de la clase MergeStageOptions. Este objeto permite especificar opciones para la etapa $merge, como la forma de gestionar documentos coincidentes.

El siguiente ejemplo crea una etapa del pipeline que fusiona los documentos del pipeline en la colección movies. El objeto MergeStageOptions especifica las siguientes opciones:

La opción OnFieldNames especifica que la operación debe usar el campo "_id" para identificar los documentos coincidentes.
La opción WhenMatched especifica que si un documento en la colección de origen coincide con un documento en la colección de destino, la operación reemplaza el documento coincidente.
La opción WhenNotMatched especifica que, si un documento en la colección de origen no coincide con un documento en la colección de destino, la operación inserta el documento en la colección de destino.

var pipeline = new EmptyPipelineDefinition<Movie>()
    .Merge(_targetCollection,
        new MergeStageOptions<Movie>()
        {
            OnFieldNames = new List<string>() { "_id" },
            WhenMatched = MergeStageWhenMatched.Replace,
            WhenNotMatched = MergeStageWhenNotMatched.Insert,
        });

{ "_id": "...", "title": "Back to the Future", "metacritic": 96 }
{ "_id": "...", "title": "Jurassic Park", "metacritic": 68 }
{ "_id": "...", "title": "The Shawshank Redemption", "metacritic": 80 }

Los ejemplos de Node.js en esta página utilizan la base de datos sample_mflix de los conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulte Primeros pasos en la documentación del controlador de MongoDB Node.js.

Para utilizar el controlador de MongoDB Node.js para agregar una etapa de $merge a una canalización de agregación, utilice el Operador $merge en un objeto de canalización.

El siguiente ejemplo crea una etapa de pipeline que fusiona los documentos del pipeline en la colección movies. El ejemplo incluye los siguientes campos:

La opción on especifica que la operación debe usar los campos "_id" y "title" para encontrar documentos coincidentes en la colección de origen y en la colección movies.
La opción whenMatched especifica que si un documento en la colección fuente coincide con un documento en la colección movies, reemplaza el documento en la colección movies.
La opción whenNotMatched especifica que si un documento en la colección de origen no coincide con un documento en la colección movies, la operación inserta el documento en la colección movies.

A continuación, el ejemplo ejecuta la canalización de agregación:

const pipeline = [
  {
    $merge: {
      into: "movies",
      on: ["_id", "title"],
      whenMatched: "replace",
      whenNotMatched: "insert"
    }
  }
];
const cursor = collection.aggregate(pipeline);
return cursor;

Volver

Coincidencia

$out

Definición

Nota

Nota

Vistas materializadas on-demand

Compatibilidad

Sintaxis

Considerations

_id Generación de campos

Crear una nueva colección si la colección de salida no existe

Nota

Salida a una colección fragmentada

Reemplazar documentos ($merge) frente a Reemplazar colección ($out)

Documentos existentes y _id y valores de la clave de partición

Tip

Restricciones de índice único

Validación de esquema

whenMatched Comportamiento del pipeline

$merge y $out Comparación

Salida a la misma colección que está siendo agregada

Advertencia

Restricciones

Ejemplos

Vista materializada on-demand: creación inicial

Nota

Tip

Vista materializada on-demand: actualizar/reemplazar datos

Tip

Solo insertar datos nuevos

Combinar resultados de múltiples colecciones

Usar el pipeline para personalizar la fusión

Usa variables para personalizar la fusión

Utiliza las variables definidas en la etapa de combinación

Utilice las variables definidas en el comando Aggregate

Utilice variables definidas en la etapa de combinación y en el comando de agregación

`_id` Generación de campos

Reemplazar documentos (`$merge`) frente a Reemplazar colección (`$out`)

Documentos existentes y `_id` y valores de la clave de partición

`whenMatched` Comportamiento del pipeline

`$merge` y `$out` Comparación