db.collection.updateMany() (mongosh method)

Parameters

The updateMany() method takes the following parameters:

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>
}

Returns

The method returns a document that contains:

• 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

• upsertedCount containing the number of upserted documents

Limitations

• updateMany() should only be used for idempotent operations.

Upsert

If upsert: true and no documents match the filter, db.collection.updateMany() creates a new document based on the filter and update parameters.

If you specify upsert: true on a sharded collection, you must include the full shard key in the filter. For additional db.collection.updateMany() behavior, see Sharded Collections.

See Update Multiple Documents with Upsert.

Update with an Update Operator Expressions Document

For the modification specification, the db.collection.updateMany() method can accept a document that only contains update operator expressions to perform.

For example:

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

Update with an Aggregation Pipeline

The db.collection.updateMany() method can accept an aggregation pipeline [ <stage1>, <stage2>, ... ] that specifies the modifications to perform. The pipeline can consist of the following stages:

• $addFields and its alias $set

• $project and its alias $unset

• $replaceRoot and its alias $replaceWith

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).

For example:

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

For examples, see Update with Aggregation Pipeline.

Capped Collections

If an update operation changes the document size, the operation will fail.

Time Series Collections

The updateMany() method is available for time series collections starting in MongoDB 5.1.

Update commands must meet the following requirements:

• You can only match on the metaField field value.

• You can only modify the metaField field value.

• Your update document can only contain update operator expressions.

• Your update command must not limit the number of documents to be updated. Set multi: true or use the updateMany() method.

• Your update command must not set upsert: true.

Sharded Collections

updateMany() exhibits the following behaviors when used with sharded collections:

• updateMany() operations that include upsert: true must include the full shard key in the filter.

• If you attempt to run updateMany() during a Range Migration or a shard key value update, the operation can miss documents in some scenarios. To ensure all documents are updated, use idempotent updates and rerun the command until no further updates are applied. For more information on idempotent updates with updateMany(), see Idempotent Updates.

• If updateMany() is run outside a transaction, operations that target more than one shard broadcast the operation to all shards in the cluster.

• If updateMany() is run inside a transaction, operations that target more than one shard only target the relevant shards.

Explainability

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

Transactions

db.collection.updateMany() can be used inside distributed transactions.

Oplog Entries

updateMany() adds an entry to the oplog (operations log) for each successfully updated document. If no documents are updated, updateMany() does not add entries to the oplog.

Idempotent Updates

The sample_mflix.movies collection contains movies with IMDB ratings. This idempotent update does the following operations:

• matches all movies with IMDB ratings less than 3.0

• increments those ratings by 0.5

• sets a ratingBoosted field to true

db.movies.updateMany(
   { "imdb.rating": { $lt: 3, $type: "number" }, ratingBoosted: { $ne: true } },
   { $inc: { "imdb.rating": 0.5 }, $set: { ratingBoosted: true } }
)

updateMany() modifies the matching movie documents individually. The individual document updates are atomic operations, but the updateMany() operation as a whole is not atomic.

If the operation fails to update all matched documents, you can safely rerun an idempotent command until no additional documents match the specified filter. In this case, each document's imdb.rating field is only updated one time regardless of how many times it is retried because the command is idempotent.

Update Multiple Documents

The sample_mflix.movies collection contains movies with a num_mflix_comments field.

The following operation finds all movies with more than 100 comments and adds a popular flag to those movies:

db.movies.updateMany( 
   { num_mflix_comments: { $gt: 100 } }, 
   { $set: { "popular" : true } } 
)

Update with Aggregation Pipeline

The db.collection.updateMany() can use an aggregation pipeline for the update. The pipeline can consist of the following stages:

• $addFields and its alias $set

• $project and its alias $unset

• $replaceRoot and its alias $replaceWith

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).

db.movies.updateMany(
   { year: { $gte: 2010, $lte: 2019 } },
   [
      { $set: { 
         combinedRatings: [ "$imdb.rating", "$tomatoes.viewer.rating" ], 
         ratingsUpdated: "$$NOW" 
      } },
      { $unset: [ "imdb.rating", "tomatoes.viewer.rating" ] }
   ]
)

db.movies.updateMany(
   { 
      year: { $gte: 2010, $lte: 2019 },
      "imdb.rating": { $exists: true },
      "tomatoes.viewer.rating": { $exists: true }
   },
   [
     { $set: { 
        combinedScore: { $trunc: [ 
           { $avg: [ "$imdb.rating", "$tomatoes.viewer.rating" ] }, 
           1 
        ] },
        scoreUpdated: "$$NOW" 
     } },
     { $set: { 
        ratingGrade: { $switch: {
           branches: [
              { case: { $gte: [ "$combinedScore", 8 ] }, then: "A" },
              { case: { $gte: [ "$combinedScore", 6 ] }, then: "B" },
              { case: { $gte: [ "$combinedScore", 4 ] }, then: "C" },
              { case: { $gte: [ "$combinedScore", 2 ] }, then: "D" }
           ],
           default: "F"
        } } 
     } }
   ]
)

Update Multiple Documents with Upsert

The following operation updates all movies released after 2020 and directed by Christopher Nolan:

db.movies.updateMany(
   { 
      year: { $gt: 2020 }, 
      directors: "Christopher Nolan" 
   },
   { $set: { "upcomingRelease": true } },
   { upsert: true }
)

In this example, since no documents match the filter, and upsert is true, updateMany() inserts a new document with a generated _id as well as the equality conditions from the 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:

db.movies.updateMany(
    { title: "The Godfather" },
    { $inc: { num_mflix_comments: 10 }, $set: { trending: true } },
    { w: "majority", wtimeout: 100 }
)

If the acknowledgment takes longer than the wtimeout limit, MongoDB throws an exception.

The following table explains the possible values of errInfo.writeConcern.provenance:

Specify Collation

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The following operation uses a case-insensitive collation to match movies with the genre "drama" with any combination of lowercase and uppercase.

db.movies.updateMany(
   { genres: "drama" },
   { $set: { genreNormalized: true } },
   { collation: { locale: "en", strength: 1 } }
)

Specify arrayFilters for an Array Update Operations

When updating an array field, you can specify arrayFilters that determine which array elements to update.

db.movies.updateMany(
   { 
      "imdb.rating": { $exists: true },
      "tomatoes.viewer.rating": { $exists: true },
      "tomatoes.critic.rating": { $exists: true },
      year: { $gte: 2010, $lte: 2015 }
   },
   [
      { $set: { 
         ratings: [
            { $multiply: ["$imdb.rating", 10] },
            { $multiply: ["$tomatoes.viewer.rating", 10] },
            { $multiply: ["$tomatoes.critic.rating", 10] }
         ]
      } }
   ]
)

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

db.movies.updateMany(
   { 
      "imdb.rating": { $exists: true },
      "tomatoes.viewer.rating": { $exists: true },
      year: { $gte: 2010, $lte: 2012 }
   },
   [
      { $set: { 
         ratingDetails: [
            { source: "imdb", score: "$imdb.rating", weight: 10 },
            { source: "tomatoes_viewer", score: "$tomatoes.viewer.rating", weight: 8 },
            { source: "tomatoes_critic", score: "$tomatoes.critic.rating", weight: 7 }
         ]
      } }
   ]
)

db.movies.updateMany(
   { ratingDetails: { $exists: true } },
   { $set: { "ratingDetails.$[elem].weight" : 10 } },
   { arrayFilters: [ { "elem.score": { $gte: 8 } } ] }
)

Specify hint for Update Operations

Create the following index on the collection:

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

The following update operation explicitly hints to use the index { rated: 1 }:

db.movies.updateMany(
   { "num_mflix_comments": { $lte: 5 }, "rated": "G" }, 
   { $set: { "familyFriendly": true } },
   { hint: { rated: 1 } }
)

To see if the hinted index is used, run the $indexStats pipeline:

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

Write Concern Errors in Sharded Clusters

When db.collection.updateMany() executes on mongos in a sharded cluster, a writeConcernError is always reported in the response, even when one or more other errors occur. In previous releases, other errors sometimes caused db.collection.updateMany() to not report write concern errors.

For example, if a document fails validation, triggering a DocumentValidationFailed error, and a write concern error also occurs, both the DocumentValidationFailed error and the writeConcernError are returned in the top-level field of the response.

User Roles and Document Updates

Starting in MongoDB 7.0, you can use the new USER_ROLES system variable to return user roles.

The example in this section shows updates to fields in a collection containing medical information. The example reads the current user roles from the USER_ROLES system variable and only performs the updates if the user has a specific role.

To use a system variable, add $$ to the start of the variable name. Specify the USER_ROLES system variable as $$USER_ROLES.

The example creates these users:

• James with a Billing role.

• Michelle with a Provider role.

Perform the following steps to create the roles, users, and collection:

db.createRole( { role: "Billing", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
db.createRole( { role: "Provider", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )

db.createUser( {
   user: "James",
   pwd: "js008",
   roles: [
      { role: "Billing", db: "test" }
   ]
} )
db.createUser( {
   user: "Michelle",
   pwd: "me009",
   roles: [
      { role: "Provider", db: "test" }
   ]
} )

db.medical.insertMany( [
   {
      _id: 0,
      patientName: "Jack Jones",
      diagnosisCode: "CAS 17",
      creditCard: "1234-5678-9012-3456"
   },
   {
      _id: 1,
      patientName: "Mary Smith",
      diagnosisCode: "ACH 01",
      creditCard: "6541-7534-9637-3456"
   }
] )

Log in as as Michelle, who has the Provider role, and perform an update:

db.auth( "Michelle", "me009" )

// Attempt to update many documents
db.medical.updateMany(
   // User must have the Provider role to perform the update
   { $expr: { $ne: [ {
      $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
   ] } },
   // Update diagnosisCode
   { $set: { diagnosisCode: "ACH 02"} }
)

The previous example uses $setIntersection to return documents where the intersection between the "Provider" string and the user roles from $$USER_ROLES.role is not empty. Michelle has the Provider role, so the update is performed.

Next, log in as as James, who does not have the Provider role, and attempt to perform the same update:

db.auth( "James", "js008" )

// Attempt to update many documents
db.medical.updateMany(
   // User must have the Provider role to perform the update
   { $expr: { $ne: [ {
      $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
   ] } },
   // Update diagnosisCode
   { $set: { diagnosisCode: "ACH 02"} }
)

The previous example does not update any documents.