OPTIONS

db.collection.updateMany()

Definition

db.collection.updateMany(filter, update, options)

New in version 3.2.

Updates multiple documents within the collection based on the filter.

The updateMany() method has the following form:

db.collection.updateMany(
   <filter>,
   <update>,
   {
     upsert: <boolean>,
     writeConcern: <document>
   }
)

The updateMany() method takes the following parameters:

Parameter Type Description
filter document

The selection criteria for the update. The same query selectors as in the find() method are available.

Specify an empty document { } to update all documents in the collection.

update document

The modifications to apply.

Use Update Operators such as $set, $unset, or $rename.

Using the update() pattern of field: value for the update parameter throws an error.

upsert boolean

Optional. When true, if no documents match the filter, a new document is created using the equality comparisons in filter with the modifications from update.

Comparison operations from the filter will not be included in the new document.

If the filter only has comparison operations, then only the modifications from the update will be applied to the new document.

See Update Multiple Documents with Upsert

writeConcern document Optional. A document expressing the write concern. Omit to use the default write concern.
Returns:A document containing:
  • A boolean acknowledged as true if the operation ran with write concern or false if write concern was disabled
  • matchedCount containing the number of matched documents
  • modifiedCount containing the number of modified documents
  • upsertedId containing the _id for the upserted document

Behavior

updateMany() updates all matching documents in the collection that match the filter, using the update criteria to apply modifications.

If upsert: true and no documents match the filter, updateMany() creates a new document based on the filter and update parameters. See Update Multiple Documents with Upsert.

Capped Collections

updateMany() throws a WriteError if the update criteria increases the size of any matching document in a capped collection.

Explainability

updateMany() is not compatible with db.collection.explain().

Use update() instead.

Examples

Update Multiple Documents

The restaurant collection contains the following documents:

{ "_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" }

The following operation updates all documents where violations are greater than 4 and $set a flag for review:

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

The operation returns:

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

The collection now contains the following documents:

{ "_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 }

If no matches were found, the operation instead returns:

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

Setting upsert: true would insert a document if no match was found.

Update Multiple Documents with Upsert

The inspectors collection contains the following documents:

{ "_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 }

The following operation updates all documents with violations that are greater than 10:

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

The operation returns:

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

The collection now contains the following documents:

{ "_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" : 92416, "inspector" : "J. Clouseau", "Sector" : 4, "Patrolling" : false }

No documents in the collection matched the filter, so a new document was created.

The following operation updates all documents with Sector greater than 4 for inspector : "R. Coltrane":

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

The operation returns:

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

The collection now contains the following documents:

{ "_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" : 92416, "inspector" : "J. Clouseau", "Sector" : 4, "Patrolling" : false },
{ "_id" : 92417, "inspector" : "R. Coltrane", "Patrolling" : false }

Since no documents matched the filter, and upsert was true, updateMany inserted the document with a generated _id, the equality operator from filter, and the update modifiers.

Update with Write Concern

Given a three member replica set, the following operation specifies a w of majority and wtimeout of 100:

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

If the acknowledgement takes longer than the wtimeout limit, the following exception is thrown:

WriteConcernError({
   "code" : 64,
   "errInfo" : {
      "wtimeout" : true
   },
   "errmsg" : "waiting for replication timed out"
}) :
undefined

The wtimeout error only indicates that the operation did not complete on time. The write operation itself can still succeed outside of the set time limit.

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.