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

Parámetros

El método db.collection.update() acepta 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 el indicador upsert establecido en true genera 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 ejecutas un update() con upsert: true y la consulta no coincide con ningún documento existente, MongoDB se negará a insertar un nuevo documento si la consulta especifica condiciones en el _id campo usando la notación de punto.

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 asegura que solo se cree un documento. Con un índice único en su lugar, las múltiples db.collection.update() operaciones ahora muestran el siguiente comportamiento:

• Exactamente una operación db.collection.update() inserta correctamente un nuevo

  documento.

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

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

  Para que otras operaciones db.collection.update() puedan actualizar el documento recién insertado, se deben cumplir todas las condiciones siguientes:

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

    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.

Puedes 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, debes especificar exactamente un documento de filtro de arreglo correspondiente. Es decir, no puedes especificar múltiples documentos de filtro de arreglo para el mismo identificador. Sin embargo, puedes especificar condiciones compuestas sobre el mismo identificador en un único documento de filtro

Resultados exitosos

El método db.collection.update() devuelve un objeto WriteResult() que contiene el estado de la operación. Al tener é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 por 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 db.collection.update() encuentra un error de nivel de confirmación de escritura (write concern), los resultados incluyen el campo WriteResult.writeError.

Insertar un nuevo documento si no existe coincidencia (Upsert)

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

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

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

  Nota

  Si se realizan varias operaciones de actualización/inserción idénticas casi simultáneamente, es posible que, al update() usarse con upsert: true, se creen documentos duplicados. Consulte la sección "Actualización/inserción con valores duplicados" para obtener más información.

Si especifica upsert: true en una colección fragmentada, debe incluir la clave de fragmentación completa filter en. Para obtener información adicional db.collection.update() sobre el comportamiento de en una colección fragmentada, consulte Colecciones fragmentadas.

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. El 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 especifica qué índice utiliza MongoDB para la operación de actualización. Especifique un índice para garantizar un plan del query coherente cuando actualice varios documentos. Este ejemplo utiliza la colección movies existente de la base de datos sample_mflix.

En primer lugar, crea un índice en el campo year:

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

La siguiente operación de actualización sugiere explícitamente que se utilice el { year: 1 } índice para actualizar todas las películas desde 20102015hasta:

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 puedas acceder en otras partes 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 reporta un writeConcernError en la respuesta, incluso cuando ocurre uno o más errores adicionales. En versiones anteriores, otros errores a veces hacían que db.collection.update() no informara los errores de nivel de confirmación de escritura (write concern).

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

Opcional. Especifica la intercalación que se debe utilizar para la operación.

La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento.

La opción de intercalación tiene la siguiente sintaxis:

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

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

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

Si no se especifica ninguna intercalación para la colección o para las operaciones, MongoDB utiliza la comparación binaria simple usada en versiones anteriores para las comparaciones de strings.

No puedes especificar varias intercalaciones para una operación. Por ejemplo, no puedes especificar diferentes intercalaciones por campo, o si realizas una búsqueda con un ordenamiento, no puedes usar una intercalación para la búsqueda y otra para el ordenamiento.

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

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