db.collection.updateMany()¶

On this page

Definition
Behavior
Examples

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.

← db.collection.updateOne() db.collection.validate() →

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.