Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.
Docs Menu
Docs Home
/ /
Etapas de agregación
Docs Home
/
Desarrollo
/
languaje del query
/
Etapas de agregación
Docs Home
/
Desarrollo
/
languaje del query
/
Etapas de agregación

$merge (etapa de agregación)

Definición

Nota

Esta página describe la etapa $merge, que produce los resultados del pipeline de agregación a una colección. Para 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 obtener más información, consulta Salida a la misma colección que se está agregando.

  • Tenga en cuenta los siguientes puntos al utilizar las $merge etapas o en $out una canalización 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 que también genera los resultados de la agregación en una $out colección,consulte$merge y Comparación.$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

en

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.

on

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. Especifica una de las siguientes opciones:

  • 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" ]

    El orden de los campos en el arreglo no importa y no se puede especificar el mismo campo varias veces.

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 implementaciones que ejecutan MongoDB 8.0 y versiones anteriores, el campo o 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 on especificados para 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 identificadores. Aunque el orden de la especificación de la clave del índice no importa, el índice único solo debe contener los on campos como 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 debe ser y por defecto _id es el campo. El índice único correspondiente _id se crea automáticamente.

    • Para usar un identificador diferente en uno o más campos para una colección que no existe, primero puede crear la colección creando un índice único en los campos deseados. Consulte la sección sobre colecciones de salida inexistentes para ver 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 predeterminado incluye todos los campos de clave de fragmentación y el _id campo. Si se especifica un on identificador diferente, el campo on debe contener todos los campos de clave de fragmentación.

whenMatched

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

Se puede especificar cualquiera de los dos:

  • Una de las cadenas de acción predefinidas:

    Acción
    Descripción

    “reemplazar”

    Reemplace el documento existente en la colección de resultados con el documento de resultados correspondiente.

    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 _id campo, elimine el _id campo en los resultados de la agregación para evitar el error, como con una etapa precedente, y así $unset sucesivamente.

    "mantenerExistente"

    Mantén el documento existente en la colección de salida.

    "fusionar" (Predeterminado)

    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 _id campo, elimine el _id campo en los resultados de la agregación para evitar el error, como con una etapa precedente, y así $unset 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:

    La canalización no puede modificar el valor del campo. Por ejemplo, si se realiza una coincidencia en el month campo, la canalización no puede modificar el month campo.

    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 las variables que se utilizarán en la secuencia 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 { new: "$$ROOT" } ROOT no se especifica, el $$new valor predeterminado es (ver). La canalización whenMatched puede acceder a la variable.

Para acceder a las variables en la canalización 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 ver ejemplos, consulte la sección "Usar variables para personalizar la fusió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 sea el _id campo. Para usar un on valor de campo diferente para una colección que no existe, primero puede 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 desea especificar el commentDate campo como identificador:

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 usted anula 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 moviesByYearAndRating colección contendrá documentos con estadísticas de películas por añoyear (campo) y clasificación de contenido (clave de fragmento); específicamente, el identificador on es ["year", "rated"] (el orden de los campos no importa). Debido a $merge que requiere un índice único con claves que correspondan a los campos del identificador on, cree 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 partición cuando se pasa la opción { unique: true } si: la clave de partición es basada en rango, la colección está vacía y no existe un índice único en la clave de partición.

En el ejemplo anterior, debido a que el identificador on es la clave de partición y otro campo, se requiere una operación separada para crear el índice correspondiente.

Reemplazar documentos ($merge) vs. Reemplazar colección ($out)

$merge Puede reemplazar un documento existente en la colección de salida si los resultados de la agregación contienen uno o más documentos que coinciden según la especificación on. 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 se especifica"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 _id campo, elimine el _id campo en los resultados de la agregación para evitar el error, como con una etapa precedente, y así $unset 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 on field(s) se elimina durante la agregación, no hay garantía de que esta se detenga. Si la agregación continúa, no hay garantía de que los documentos no tengan on valores de campo duplicados.

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:

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 canalización de agregación.

  • El valor de whenNotMatched insertes.

  • No hay coincidencia para un documento en la colección de salida.

$merge y comparación $out

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

    Véase también Reemplazar documentos$merge () frente a Reemplazar colección$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$mergeenvía la salida a la misma colección que se está agregando, los documentos pueden actualizarse varias veces o la operación puede generar un bucle infinito. Este comportamiento se produce cuando la actualización realizada por$mergecambia la ubicación física de los documentos almacenados en el disco. Cuando cambia la ubicación física de un documento, $mergepuede considerarlo como un documento completamente nuevo, lo que genera actualizaciones adicionales. Para obtener más información sobre este comportamiento, consulte el Problema de Halloween.

$merge puede generar una salida a la misma colección que se está agregando. También puede generar una salida a una colección que aparece en otras etapas de la canalización,$lookup como.

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.

ver definición
Separado de la vista materializada

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$mergeno se puede usar junto con la preocupación de lectura"linearizable". Es decir, si especifica la preocupación de lectura"linearizable"paradb.collection.aggregate(), no puede incluir la etapa$mergeen la canalización.

Ejemplos

Volver
Coincidencia
Next
$out
Califique esta página

En esta página