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

Parámetros

El método updateMany() toma los siguientes parámetros:

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

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

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

Devuelve

El método devuelve un documento que contiene:

• Un valor booleano acknowledged en true si la operación se ejecutó con nivel de confirmación de escritura (write concern) o en false si el nivel de confirmación de escritura (write concern) estaba deshabilitado

• matchedCount que contiene el número de documentos coincidentes

• modifiedCount que contiene el número de documentos modificados

• upsertedId que contiene el _id para el documento actualizado o insertado

• upsertedCount que contiene la cantidad de documentos actualizados o insertados

Limitaciones

• updateMany() debería usarse solo para operaciones idempotentes.

Inserción

Si upsert: true y ningún documento coincide con el filter, db.collection.updateMany() crea un nuevo documento basado en los parámetros filter y update.

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

Consulta Actualizar varios documentos con inserción.

Actualiza con un documento de actualización de expresiones de operador

Para la especificación de modificación, el método db.collection.updateMany() puede aceptar un documento que solo contiene expresiones de Operadores de actualización para ejecutar.

Por ejemplo:

db.collection.updateMany(
   <query>,
   { $set: { status: "D" }, $inc: { quantity: 2 } },
   ...
)

Actualiza con un pipeline de agregación

El método db.collection.updateMany() 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.

Por ejemplo:

db.collection.updateMany(
   <query>,
   [
      { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
      { $unset: [ "misc1", "misc2" ] }
   ]
   ...
)

Para ver ejemplos, consulta Actualización con pipeline de agregación.

Colecciones con tamaño fijo

Si una operación de actualización cambia el tamaño del documento, la operación fallará.

Colecciones de series de tiempo

El método updateMany() está disponible para colecciones de series de tiempo a partir de MongoDB 5.1.

Los comandos de actualización deben cumplir con los siguientes requisitos:

• Solo puedes hacer coincidir el valor del campo metaField.

• Solo puedes modificar el valor del campo metaField.

• El documento de actualización solo puede contener expresiones de operador de actualización.

• Su comando para actualizar no debe limitar el número de documentos que se deben actualizar. Establezca multi: true o utilice el método updateMany().

• El comando de actualización no debe establecer inserción: true.

Colecciones fragmentadas

updateMany() presenta los siguientes comportamientos cuando se utiliza con colecciones fragmentadas:

• updateMany() las operaciones que incluyen upsert: true deben incluir la clave de fragmentación completa en el filter.

• Si intentas ejecutar updateMany() durante una migración de rangos o una actualización de valores de la clave de partición, la operación puede omitir documentos en algunos casos. Para asegurarte de que todos los documentos estén actualizados, utiliza actualizaciones idempotentes y vuelve a ejecutar el comando hasta que no se apliquen más actualizaciones. Para obtener más información sobre las actualizaciones idempotentes con updateMany(), consulta Actualizaciones idempotentes.

• Si updateMany() se ejecuta fuera de una transacción, las operaciones que apuntan a más de una partición difunden la operación a todas las particiones del clúster.

• Si updateMany() se ejecuta dentro de una transacción, las operaciones que apuntan a más de una partición solo afectan a las particiones relevantes.

Explicabilidad

updateMany() no es compatible con db.collection.explain().

Transacciones

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

Entradas de OpLog

updateMany() añade una entrada al oplog (registro de operaciones) por cada documento actualizado con éxito. Si no se actualizan documentos, updateMany() no añade entradas al oplog.

Idempotent Updates

El siguiente ejemplo demuestra una actualización idempotente con updateMany():

Una empresa está otorgando un aumento de $1,000 a todos los empleados que ganan menos de $100,000.

Considere una colección employees con los siguientes documentos:

db.employees.insertMany( [
   { _id: 1, name: "Rob", salary: 37000 },
   { _id: 2, name: "Trish", salary: 65000 },
   { _id: 3, name: "Zeke", salary: 99999 },
   { _id: 4, name: "Mary", salary: 200000 }
] )

El siguiente comando coincide con todos los empleados que ganan menos de $100,000 y no han recibido un aumento, incrementa esos salarios en $1,000 y establece raiseApplied como verdadero:

db.employees.updateMany(
   { salary: { $lt: 100000 }, raiseApplied: { $ne: true } },
   { $inc: { salary: 1000 }, $set: { raiseApplied: true } }
)

updateMany() modifica los documentos employee coincidentes de forma individual. Las actualizaciones individuales de documentos son operaciones atómicas, pero la operación updateMany() en su totalidad no es atómica.

Si la operación no logra actualizar todos los documentos coincidentes, puedes volver a ejecutar de forma segura un comando idempotente hasta que no haya documentos adicionales que coincidan con el filtro especificado. En este caso, el campo salary de cada documento se actualiza solo una vez, sin importar cuántas veces se reintente, porque el comando es idempotente.

Después de que todos los empleados elegibles hayan recibido sus aumentos, puedes eliminar el campo raiseApplied con el siguiente comando:

db.employees.updateMany(
   { },
   { $unset: { raiseApplied: 1 } }
)

Actualiza varios documentos

La colección restaurant contiene los siguientes documentos:

db.restaurant.insertMany( [
   { _id: 1, name: "Central Perk Cafe", violations: 3 },
   { _id: 2, name: "Rock A Feller Bar and Grill", violations: 2 },
   { _id: 3, name: "Empire State Sub", violations: 5 },
   { _id: 4, name: "Pizza Rat's Pizzaria", violations: 8 },
] )

La siguiente operación actualiza todos los documentos donde las violations son mayores que 4 y $set una marca para revisar:

try {
   db.restaurant.updateMany(
      { violations: { $gt: 4 } },
      { $set: { "Review" : true } }
   );
} catch (e) {
   print(e);
}

La operación arroja:

{ "acknowledged" : true, "matchedCount" : 2, "modifiedCount" : 2 }

La colección ahora contiene los siguientes documentos:

{ _id: 1, name: "Central Perk Cafe", violations: 3 }
{ _id: 2, name: "Rock A Feller Bar and Grill", violations: 2 }
{ _id: 3, name: "Empire State Sub", violations: 5, Review: true }
{ _id: 4, name: "Pizza Rat's Pizzaria", violations: 8, Review: true }

Si no se encuentra ninguna coincidencia, la operación arroja lo siguiente:

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

Al configurar upsert: true se insertaría un documento si no se encuentra ninguna coincidencia.

Actualiza con el pipeline de agregación

El db.collection.updateMany() puede utilizar un pipeline de agregación para actualizar. 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.students.insertMany( [
   { _id: 1, student: "Skye", points: 75, commentsSemester1: "great at math", commentsSemester2: "loses temper", lastUpdate: ISODate("2019-01-01T00:00:00Z") },
   { _id: 2, students: "Elizabeth", points: 60, commentsSemester1: "well behaved", commentsSemester2: "needs improvement", lastUpdate: ISODate("2019-01-01T00:00:00Z") }
] )

db.students.updateMany(
   { },
   [
      { $set: { comments: [ "$commentsSemester1", "$commentsSemester2" ], lastUpdate: "$$NOW" } },
      { $unset: [ "commentsSemester1", "commentsSemester2" ] }
   ]
)

{ _id: 1, student: "Skye", status: "Modified", points: 75, lastUpdate: ISODate("2020-01-23T05:11:45.784Z"), comments: [ "great at math", "loses temper" ] }
{ _id: 2, student: "Elizabeth", status: "Modified", points: 60, lastUpdate: ISODate("2020-01-23T05:11:45.784Z"), comments: [ "well behaved", "needs improvement" ] }

db.students3.insertMany( [
   { _id: 1, tests: [ 95, 92, 90 ], lastUpdate: ISODate("2019-01-01T00:00:00Z") },
   { _id: 2, tests: [ 94, 88, 90 ], lastUpdate: ISODate("2019-01-01T00:00:00Z") },
   { _id: 3, tests: [ 70, 75, 82 ], lastUpdate: ISODate("2019-01-01T00:00:00Z") }
] )

db.students3.updateMany(
   { },
   [
     { $set: { average : { $trunc: [ { $avg: "$tests" }, 0 ] } , lastUpdate: "$$NOW" } },
     { $set: { grade: { $switch: {
                           branches: [
                               { case: { $gte: [ "$average", 90 ] }, then: "A" },
                               { case: { $gte: [ "$average", 80 ] }, then: "B" },
                               { case: { $gte: [ "$average", 70 ] }, then: "C" },
                               { case: { $gte: [ "$average", 60 ] }, then: "D" }
                           ],
                           default: "F"
     } } } }
   ]
)

{ _id: 1, tests: [ 95, 92, 90 ], lastUpdate: ISODate("2020-01-24T17:31:01.670Z"), average: 92, grade: "A" }
{ _id: 2, tests: [ 94, 88, 90 ], lastUpdate: ISODate("2020-01-24T17:31:01.670Z"), average: 90, grade: "A" }
{ _id: 3, tests: [ 70, 75, 82 ], lastUpdate: ISODate("2020-01-24T17:31:01.670Z"), average: 75, grade: "C" }

Actualiza múltiples documentos con inserción

La colección inspectors contiene los siguientes documentos:

db.inspectors.insertMany( [
   { _id: 92412, inspector: "F. Drebin", Sector: 1, Patrolling: true },
   { _id: 92413, inspector: "J. Clouseau", Sector: 2, Patrolling: false },
   { _id: 92414, inspector: "J. Clouseau", Sector: 3, Patrolling: true },
   { _id: 92415, inspector: "R. Coltrane", Sector: 3, Patrolling: false }
] )

La siguiente operación actualiza todos los documentos con Sector mayor que 4 e inspector igual a "R. Coltrane":

try {
   db.inspectors.updateMany(
      { "Sector" : { $gt : 4 }, "inspector" : "R. Coltrane" },
      { $set: { "Patrolling" : false } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

La operación arroja:

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : ObjectId("56fc5dcb39ee682bdc609b02"),
   "upsertedCount": 1
}

La colección ahora contiene los siguientes documentos:

{ _id: 92412, inspector: "F. Drebin", Sector: 1, Patrolling: true },
{ _id: 92413, inspector: "J. Clouseau", Sector: 2, Patrolling: false },
{ _id: 92414, inspector: "J. Clouseau", Sector: 3, Patrolling: true },
{ _id: 92415, inspector: "R. Coltrane", Sector: 3, Patrolling: false },
{ _id: ObjectId("56fc5dcb39ee682bdc609b02"), inspector: "R. Coltrane", Patrolling: false }

Dado que ningún documento coincidió con el filtro y upsert era true, updateMany() insertó el documento con un _id generado, las condiciones de igualdad del filter y los modificadores update.

Actualizar con nivel de confirmación de escritura (Write Concern)

Dado un set de réplicas de tres nodos, la siguiente operación especifica un w de majority y un wtimeout de 100:

try {
   db.restaurant.updateMany(
       { "name" : "Pizza Rat's Pizzaria" },
       { $inc: { "violations" : 3}, $set: { "Closed" : true } },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print(e);
}

Si el reconocimiento tarda más que el límite de wtimeout, se obtiene la siguiente excepción:

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

La siguiente tabla explica los posibles valores de errInfo.writeConcern.provenance:

Especificar la intercalació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.

Una colección myColl tiene los siguientes documentos:

db.myColl.insertMany( [
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
] )

La siguiente operación incluye la opción de intercalación:

db.myColl.updateMany(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

Especifique arrayFilters para una operación de actualización de matriz

Al actualizar el campo de un arreglo, puede especificar arrayFilters que determinen qué elementos del arreglo actualizar.

db.students.insertMany( [
   { _id: 1, grades: [ 95, 92, 90 ] },
   { _id: 2, grades: [ 98, 100, 102 ] },
   { _id: 3, grades: [ 95, 110, 100 ] }
] )

db.students.updateMany(
   { grades: { $gte: 100 } },
   { $set: { "grades.$[element]" : 100 } },
   { arrayFilters: [ { "element": { $gte: 100 } } ] }
)

{ _id: 1, grades: [ 95, 92, 90 ] }
{ _id: 2, grades: [ 98, 100, 100 ] }
{ _id: 3, grades: [ 95, 100, 100 ] }

db.students2.insertMany( [
   {
      _id: 1,
      grades: [
         { grade: 80, mean: 75, std: 6 },
         { grade: 85, mean: 90, std: 4 },
         { grade: 85, mean: 85, std: 6 }
      ]
   },
   {
      _id: 2,
      grades: [
         { grade: 90, mean: 75, std: 6 },
         { grade: 87, mean: 90, std: 3 },
         { grade: 85, mean: 85, std: 4 }
      ]
   }
] )

db.students2.updateMany(
   { },
   { $set: { "grades.$[elem].mean" : 100 } },
   { arrayFilters: [ { "elem.grade": { $gte: 85 } } ] }
)

{
   _id: 1,
   grades: [
      { grade: 80, mean: 75, std: 6 },
      { grade: 85, mean: 100, std: 4 },
      { grade: 85, mean: 100, std: 6 }
   ]
}
{
   _id: 2,
   grades: [
      { grade: 90, mean: 100, std: 6 },
      { grade: 87, mean: 100, std: 3 },
      { grade: 85, mean: 100, std: 4 }
   ]
}

Especifica hint para las operaciones de actualización

Crea una colección de ejemplo students con los siguientes documentos:

db.students.insertMany( [
   { _id: 1, student: "Richard", grade: "F", points:  0,  comments1: null, comments2: null },
   { _id: 2, student: "Jane", grade: "A", points: 60,  comments1: "well behaved", comments2: "fantastic student" },
   { _id: 3, student: "Ronan", grade: "F", points:  0,  comments1: null, comments2: null },
   { _id: 4, student: "Noah", grade: "D", points: 20,  comments1: "needs improvement", comments2: null },
   { _id: 5, student: "Adam", grade: "F", points:  0,  comments1: null, comments2: null },
   { _id: 6, student: "Henry", grade: "A", points: 86,  comments1: "fantastic student", comments2: "well behaved" }
] )

Cree los siguientes índices en la colección:

db.students.createIndex( { grade: 1 } )

La siguiente operación de actualización indica explícitamente que se debe usar el índice { grade: 1 }:

db.students.updateMany(
   { "points": { $lte: 20 }, "grade": "F" },
   { $set: { "comments1": "failed class" } },
   { hint: { grade: 1 } }
)

El comando de actualización devuelve lo siguiente:

{ "acknowledged" : true, "matchedCount" : 3, "modifiedCount" : 3 }

Para ver si se utiliza el índice insinuado, ejecuta el pipeline $indexStats :

db.students.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } }, { $match: {key: { grade: 1 } } } ] )

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

Cuando db.collection.updateMany() 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.updateMany() 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.