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 intenta 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 db.collection.update() operaciones finalizan la fase de consulta antes de que cualquier cliente inserte datos exitosamente, y no hay un índice único en el name campo, cada db.collection.update() operación puede resultar en una inserción, creando múltiples documentos name: Andy con.

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 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 en el predicado de igualdad coinciden con los campos en el

    Patrón de clave de índice único.

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

    Patrón de clave de índice único.

Operaciones de actualización de matrices

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 que contiene el estado de la WriteResult() WriteResult() operación. Si la operación se realiza correctamente, el objeto contiene el número de documentos que cumplen la condición de consulta, 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 db.collection.update() método encuentra errores de escritura, los resultados incluyen el WriteResult.writeConcernError campo.

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 permite especificar el índice que MongoDB debe usar para la operación de actualización. Esto resulta útil al actualizar varios documentos y garantizar el uso de un índice específico para mejorar el rendimiento. Este ejemplo utiliza la colección movies existente 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 sugiere explícitamente utilizar el { year: 1 } índice para actualizar todas las películas 2010de2015 a:

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 (establecida en "The Matrix") y newTitle (establecida en "The Matrix Reloaded")

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

• Utiliza una canalización 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 luego de que el servidor primario y al menos un servidor secundario reconocen la escritura, como se especifica mediante 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
   }
)