db.colección.actualizar() (método mongosh)

Parámetros

El método db.collection.update() toma los siguientes parámetros:

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

Devuelve

El método devuelve un documento WriteResult que contiene el estado de la operación.

Limitaciones

Si configuras multi: true, usa el método update() solo para operaciones idempotentes.

Uso de $expr en una actualización con Upsert

Intentar usar el operador $expr con la bandera de inserción configurada en true generará un error.

Colecciones fragmentadas

Para usar db.collection.update() con multi: false en una colección particionada, se debe incluir una coincidencia exacta en el campo _id o dirigirse a una única partición (por ejemplo, incluyendo la clave de partición).

Cuando el db.collection.update() realiza operaciones de actualización (y no operaciones de reemplazo de documentos), db.collection.update() puede dirigirse a varias particiones.

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Transacciones

db.collection.update() puede usarse dentro de transacciones distribuidas.

Entradas de OpLog

Si una operación db.collection.update() actualiza con éxito uno o más documentos, la operación añade una entrada en el oplog (registro de operaciones). Si la operación falla o no encuentra ningún documento para actualizar, la operación no agrega una entrada en el OpLog.

Inserción con query punteada _id

Cuando se ejecuta un update() con upsert: true y el query no coincide con ningún documento existente, MongoDB se negará a insertar un nuevo documento si el query especifica condiciones en el campo _id usando notación de puntos.

Esta restricción asegura que el orden de los campos incrustados en el documento _id esté bien definido y no dependa del orden especificado en el query.

Si intentas insertar un documento de esta manera, MongoDB genera un error.

Inserción con valores duplicados

Los upserts pueden crear documentos duplicados, a menos que haya un índice único para evitar duplicados.

Si todas las operaciones db.collection.update() terminan la fase de query antes de que cualquier cliente inserte datos exitosamente, y no existe un índice único en el campo name, cada operación db.collection.update() puede resultar en una inserción, creando múltiples documentos con name: Andy.

Un índice único en el campo name garantiza la creación de un solo documento. Con un índice único, las operaciones múltiples db.collection.update() ahora presentan el siguiente comportamiento:

• Exactamente una operación db.collection.update() insertará con éxito un nuevo

  documento.

• Outras operaciones db.collection.update() atualizam a recém-inserida

  documento o fallar debido a una colisión de clave única.

  Para que otras db.collection.update() operaciones actualicen el documento recién insertado, se deben cumplirtodas las siguientes condiciones:

  • La colección de destino tiene un índice único que causaría una

    error de clave duplicada.

  • La operación de actualización no es updateMany o multi lo es

    false.

  • La condición de coincidencia de actualización es:

    • Un único predicado de igualdad. Por ejemplo { "fieldA" : "valueA" }

    • Un AND lógico de predicados de igualdad. Por ejemplo { "fieldA" : "valueA", "fieldB" : "valueB" }

  • Los campos del predicado de igualdad coinciden con los campos en el

    patrón único de clave de índice.

  • La operación de actualización no modifica ningún campo en el

    patrón único de clave de índice.

Operaciones de actualización de arreglos

En el documento de actualización, usa el operador posicional filtrado $[<identifier>] para definir un identificador, al que luego puedes hacer referencia en los documentos de filtro de arreglo. No puedes tener un documento de filtro de arreglo para un identificador si dicho identificador no está incluido en el documento de actualización.

El <identifier> debe comenzar con una letra minúscula y contener solo caracteres alfanuméricos.

Puede incluir el mismo identificador varias veces en el documento de actualización; sin embargo, para cada identificador distinto$[identifier] () en el documento de actualización, debe especificar exactamente un documento de filtro de matriz correspondiente. Es decir, no puede especificar varios documentos de filtro de matriz para el mismo identificador. Sin embargo, puede especificar condiciones compuestas para el mismo identificador en un solo documento de filtro.

Resultados exitosos

El método db.collection.update() devuelve un objeto WriteResult() que contiene el estado de la operación. En caso de éxito, el objeto WriteResult() contiene el número de documentos que coincidieron con la condición de la query, el número de documentos insertados mediante la actualización, y el número de documentos modificados.

Errores de nivel de confirmación de escritura

Si el método db.collection.update() encuentra errores de nivel de confirmación de escritura (write concern), los resultados incluyen el campo WriteResult.writeConcernError.

La siguiente tabla explica los posibles valores de WriteResult.writeConcernError.provenance:

Errores no relacionados con el nivel de confirmación de escritura (write concern)

Si el método encuentra un error que no db.collection.update() WriteResult.writeError es de escritura, los resultados incluyen el campo.

Insertar un nuevo documento si no existe ninguna coincidenciaUpsert ()

Cuando especificas la opción inserción: true:

• Si los documentos coinciden con los criterios de query, db.collection.update() realiza una actualización.

• Si ningún documento cumple con los criterios del query, db.collection.update() inserta un único documento.

  Nota

  Si se emiten múltiples inserciones idénticas aproximadamente al mismo tiempo, es posible que update() utilizado con upsert: true cree documentos duplicados. Consulta Inserción con valores duplicados para más información.

Si especificas upsert: true en una colección particionada, debes incluir la clave de partición completa en el filter. Para obtener información adicional sobre el comportamiento db.collection.update() en una colección particionada, consulta Colecciones particionadas.

Las siguientes pestañas muestran una variedad de usos del modificador upsert con update().

db.movies.update(
   { title: "Test Movie 12345" },
   { 
      $set: {
         title: "Test Movie 12345", 
         year: 2024, 
         genres: [ "Documentary" ],
         rated: "NR"
      }
   },
   { upsert: true }
)

db.movies.update(
   { title: "Test Movie 67890" },   // Query parameter
   {                                // Update document
      $set: { rated: "PG" },
      $setOnInsert: { year: 2024, type: "movie" }
   },
   { upsert: true }                 // Options
)

db.movies.update(
   { title: "Test Movie ABC123" },  // Query parameter
   [                                // Aggregation pipeline
      { $set: { 
         year: 2024, 
         type: "movie",
         rated: "NR",
         lastModified: "$$NOW" 
      } }
   ],
   { upsert: true }   // Options
)

db.movies.update(
   { title: { $in: ["The Godfather", "The Matrix"] } },
   { $set: { test_upsert_field: true } },
   { upsert: true, multi: true }
)

db.movies.update(
   { "title": "Test Movie Unique789" },
   { $set: { year: 2024, type: "movie" } },
   { upsert: true, multi: true }
)

Actualiza con el pipeline de agregación

El método db.collection.update() puede aceptar una pipeline de agregación [ <stage1>, <stage2>, ... ] que especifica las modificaciones a realizar. La pipeline puede constar de las siguientes etapas:

• $addFields y su alias $set

• $project y su alias $unset

• $replaceRoot y su alias $replaceWith

El uso de un pipeline de agregación permite una instrucción de actualización más expresiva, como expresar actualizaciones condicionales basadas en los valores actuales de los campos o actualizar un campo con el valor de otros campos.

db.movies.update(
   { title: "The Godfather" },
   [
      { $set: { 
            displayTitle: { $concat: [ "$title", " (", { $toString: "$year" }, ")" ] },
            lastModified: "$$NOW" 
         } 
      }
   ]
)

db.movies.update(
   { 
      year: 2015,
      "imdb.rating": { $type: "number" },
      "tomatoes.viewer.rating": { $type: "number" }
   },
   [
      { $set: { 
         combinedScore: { 
            $round: [ 
               { $avg: [ 
               { $multiply: [ "$imdb.rating", 10 ] }, 
               { $multiply: [ "$tomatoes.viewer.rating", 10 ] } 
               ] }, 
               1 
            ] 
         }, 
         lastUpdate: "$$NOW" 
         } 
      },
      { $set: { 
         grade: { 
            $switch: {
               branches: [
               { case: { $gte: [ "$combinedScore", 80 ] }, then: "A" },
               { case: { $gte: [ "$combinedScore", 70 ] }, then: "B" },
               { case: { $gte: [ "$combinedScore", 60 ] }, then: "C" },
               { case: { $gte: [ "$combinedScore", 50 ] }, then: "D" }
               ],
               default: "F"
            } 
         } 
         } 
      }
   ],
   { multi: true }
)

Especifica arrayFilters para las operaciones de actualización de arreglos

db.movies.update(
   { languages: "English" },
   { $set: { "languages.$[element]" : "EN" } },
   {
      arrayFilters: [ { "element": "English" } ],
      multi: true
   }
)

db.movies.update(
   { title: "The Godfather" },
   { $set: { "writers.$[elem]" : { $concat: [ "$elem", " - UPDATED" ] } } },
   {
      arrayFilters: [ { "elem": { $regex: /screenplay/ } } ]
   }
)

Especifica hint para las operaciones de actualización

La opción hint le permite especificar qué índice MongoDB debe usar para la operación de actualización. Esto es útil al actualizar varios documentos y se desea garantizar que se utilice un índice específico para el rendimiento. Este ejemplo utiliza la colección existente movies de la base de datos sample_mflix.

Primero, crea un índice en el campo year:

db.movies.createIndex( { year: 1 } )

La siguiente operación de actualización indica explícitamente usar el índice { year: 1 } para actualizar todas las películas de 2010-2015:

db.movies.update(
   { year: { $gte: 2010, $lte: 2015 } },  // Query parameter
   { $set: { decade: "2010s" } },             // Update document
   { multi: true, hint: { year: 1 } }          // Options
)

Para ver el índice utilizado, ejecuta explain en la operación:

db.movies.explain().update(
   { title: "The Godfather", year: { $gte: 1970 } },
   { $set: { test_hint_field: true } },
   { hint: { year: 1 } }
)

El db.collection.explain().update() no modifica los documentos.

Usar variables en let

Para definir variables a las que puedes acceder en otros lugares del comando, utiliza la opción let.

El ejemplo:

• Define dos variables en la opción let: targetTitle (configurada en "The Matrix") y newTitle (configurada en "The Matrix Reloaded")

• Utiliza $expr en el filtro de query para comparar el campo title del documento con la variable $$targetTitle

• Utiliza una pipeline de agregación con $set para actualizar el campo title al valor de $$newTitle

db.movies.update(
   { $expr: { $eq: [ "$title", "$$targetTitle" ] } },
   [ { $set: { sequel: "$$sequelTitle" } } ],
   { let : { targetTitle: "The Matrix", sequelTitle: "The Matrix Reloaded" } }
)

Anular el nivel de confirmación de escritura (write concern) por defecto

La siguiente operación a un set de réplicas especifica un nivel de confirmación de escritura (write concern) de w: 2 con un wtimeout de 5000 milisegundos. Esta operación regresa después de que el guardado se propaga tanto al primario como a un secundario, o expira después de 5 segundos.

db.movies.update(
   { num_mflix_comments: { $lte: 10 } },
   { $set: { featured: true } },
   {
      multi: true,
      writeConcern: { w: 2, j: true, wtimeout: 5000 }
   }
)

La operación se completa exitosamente después de que la escritura sea reconocida por el primario y al menos un secundario, según lo especificado por w: 2.

Errores de nivel de confirmación de escritura (write concern) en clústeres particionados

Cuando db.collection.update() se ejecuta en mongos en un clúster fragmentado, siempre se informa de un writeConcernError en la respuesta, incluso cuando se producen uno o más errores adicionales. En versiones anteriores, otros errores a veces causaban que db.collection.update() no reportara errores de nivel de confirmación de escritura.

Por ejemplo, si un documento no supera la validación, activando un error DocumentValidationFailed, y también ocurre un error de nivel de confirmación de escritura, tanto el error DocumentValidationFailed como el writeConcernError se devuelven en el campo de nivel superior de la respuesta.

Especificar la intercalación

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.

Esta operación actualiza todas las películas con títulos que comienzan con night y utiliza strength: 1 para la comparación sin distinguir entre mayúsculas y minúsculas:

db.movies.update(
   { title: /^night/i },
   { $set: { updated: true } },
   {
      collation: { locale: "en", strength: 1 },
      multi: true
   }
)