update (database command)

Update Statements

Each element of the updates array is an update statement document. Each document contains the following fields:

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

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

Returns

The command returns a document that contains the status of the operation. For example:

{
   "ok" : 1,
   "nModified" : 0,
   "n" : 1,
   "upserted" : [
      {
         "index" : 0,
         "_id" : ObjectId("52ccb2118908ccd753d65882")
      }
   ]
}

For details of the output fields, see Output.

Limitations

If you set multi: true, use the update command only for idempotent operations.

Update with an Update Operator Expressions Document

The update statement field u can accept a document that only contains update operator expressions. For example:

updates: [
   {
     q: <query>,
     u: { $set: { status: "D" }, $inc: { quantity: 2 } },
      ...
   },
   ...
]

Then, the update command updates only the corresponding fields in the document.

Update with a Replacement Document

The update statement field u field can accept a replacement document, i.e. the document contains only field:value expressions. For example:

updates: [
   {
      q: <query>,
      u: { status: "D", quantity: 4 },
      ...
   },
   ...
]

Then the update command replaces the matching document with the update document. The update command can only replace a single matching document; i.e. the multi field cannot be true. The update command does not replace the _id value.

Multi-Update Failures

If a single document fails to update in an update command with the multi parameter set to true, no further documents update as part of that command.

For example, the sample_mflix.movies collection contains movies with imdb.rating fields. Create a document validator on the movies collection with a rule that the imdb.rating value must be less than or equal to 10:

db.runCommand( 
   { 
      update: "movies",
      updates: [
      {
         q: { 
            year: { $gte: 2000, $lte: 2005 },
            "imdb.rating": { $type: "number" }
         }, 
         u: { $inc: { "imdb.rating": 1 } },
         multi: true
      }
      ]
   }
)

If any movie already has a rating of 10, incrementing it would violate the validator rule (rating > 10). When this happens, the update stops and no further documents are updated, even if thousands of documents matched the query.

Update with an Aggregation Pipeline

The update statement field u field 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:

updates: [
   {
      q: <query>,
      u: [
        { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
        { $unset: [ "misc1", "misc2" ] }
      ],
      ...
   },
   ...
]

For examples, see Update with Aggregation Pipeline.

Upsert with Unique Index

Upserts can create duplicate documents, unless there is a unique index to prevent duplicates.

Consider an example where no document with the name Andy exists and multiple clients issue the following command at roughly the same time:

db.runCommand(
   {
     update: "people",
     updates: [
       { q: { name: "Andy" }, u: { $inc: { score: 1 } }, multi: true, upsert: true }
     ]
   }
)

If all update operations finish the query phase before any client successfully inserts data, and there is no unique index on the name field, each update operation may result in an insert, creating multiple documents with name: Andy.

A unique index on the name field ensures that only one document is created. With a unique index in place, the multiple update operations now exhibit the following behavior:

• Exactly one update operation will successfully insert a new document.

• Other update operations either update the newly-inserted document or fail due to a unique key collision.

  In order for other update operations to update the newly-inserted document, all of the following conditions must be met:

  • The target collection has a unique index that would cause a duplicate key error.

  • The update operation is not updateMany or multi is false.

  • The update match condition is either:

    • A single equality predicate. For example { "fieldA" : "valueA" }

    • A logical AND of equality predicates. For example { "fieldA" : "valueA", "fieldB" : "valueB" }

  • The fields in the equality predicate match the fields in the unique index key pattern.

  • The update operation does not modify any fields in the unique index key pattern.

The following table shows examples of upsert operations that, when a key collision occurs, either result in an update or fail.

{ name : 1 }

db.people.updateOne(
   { name: "Andy" },
   { $inc: { score: 1 } },
   { upsert: true }
)

{ name : 1 }

db.people.updateOne(
   { name: { $ne: "Joe" } },
   { $set: { name: "Andy" } },
   { upsert: true }
 )

{ name : 1 }

db.people.updateOne(
  { name: "Andy", email: "andy@xyz.com" },
  { $set: { active: false } },
  { upsert: true }
)

Limits

For each update element in the updates array, the sum of the query and the update sizes (i.e. q and u ) must be less than or equal to the maximum BSON document size.

The total number of update statements in the updates array must be less than or equal to the maximum bulk size.

Schema Validation

The update command adds support for the bypassDocumentValidation option, which lets you bypass schema validation when inserting or updating documents in a collection with validation rules.

Sharded Collections

Transactions

update can be used inside distributed transactions.

Update Specific Fields of One Document

Use update operators to update only the specified fields of a document.

For example, documents in the movies collection from the sample_mflix database contain fields such as title, year, and num_mflix_comments.

The following command uses the $set and $inc update operators to update the year and the num_mflix_comments fields of a document where the title equals "The Godfather":

db.runCommand(
   {
      update: "movies",
      updates: [
         {
            q: { title: "The Godfather" }, u: { $set: { year: 1972 }, $inc: { num_mflix_comments: 1 } }
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Because <update> document does not specify the optional multi field, the update only modifies one document, even if more than one document matches the q match condition.

See Output for details.

Update Specific Fields of Multiple Documents

Use update operators to update only the specified fields of a document, and include the multi field set to true in the update statement.

For example, documents in the movies collection from the sample_mflix database contain fields such as year and num_mflix_comments.

The following command uses the $inc update operator to increment the num_mflix_comments field for all movies released in 1924:

db.runCommand(
   {
      update: "movies",
      updates: [
         { 
            q: { year: 1924 }, 
            u: { $inc: { num_mflix_comments: 1 }, $set: { classic: true, era: "silent" } }, 
            multi: true 
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Because the multi field is set to true, the update modifies all 6 documents that match the query specified in the q field and returns the following output:

{ n: 6, nModified: 6, ok: 1 }

See Output for details.

Update with Aggregation Pipeline

The update command 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.runCommand(
   {
      update: "users",
      updates: [
         { 
            q: { name: "Robert Baratheon" },  
            u: [ 
               { $set: { full_info: { $concat: [ "$name", " - ", "$email" ] } } },
               { $set: { status: "active" } }
            ], 
            multi: false
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

db.runCommand(
   {
      update: "movies",
      updates: [
         { 
            q: { title: "The Great Train Robbery" },  
            u: [ 
                  { $set: { age: { $subtract: [ 2026, "$year" ] } } },
                  { $set: { era: { $switch: { 
                                       branches: [
                                             { case: { $lt: [ "$year", 1960 ] }, then: "Classic" },
                                             { case: { $lt: [ "$year", 1980 ] }, then: "Golden Age" },
                                             { case: { $lt: [ "$year", 2000 ] }, then: "Modern" },                                                   
                                             { case: { $gte: [ "$year", 2000 ] }, then: "Contemporary" }
                                       ],
                                       default: "Unknown" 
                  } } } } 
            ], 
            multi: false
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Bulk Update

The following example performs multiple update operations in a single command to both update existing documents and insert new documents. The operation:

• marks highly-rated Horror movies from 2015 as featured

• categorizes short Drama and Romance movies from 2012 as melodrama

• upserts a new Science Fiction movie from 2024 if it doesn't exist

db.runCommand(
   {
      update: "movies",
      updates: [
         // Update highly-rated Horror movies from 2015
         { 
            q: { year: 2015, genres: "Horror", "imdb.rating": { $gte: 7 } }, 
            u: { $set: { featured: true } },
            multi: true
         },
         // Update short Drama/Romance movies from 2012
         { 
            q: { year: 2012, genres: { $all: ["Drama", "Romance"] }, runtime: { $lt: 90 } }, 
            u: { $set: { category: "melodrama" } },
            multi: true
         },
         // Upsert a new movie from 2026
         { 
            q: { title: "A New Movie", year: 2026 }, 
            u: { 
               $set: { 
                  genres: ["Sci-Fi", "Adventure"],
                  runtime: 142,
                  "imdb.rating": 8.5,
                  featured: true
               }
            },
            upsert: true
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The returned document shows that the command modified existing documents and inserted a new document via upsert. See Output for details.

{
  n: 16,
  upserted: [
    {
      index: 2,
      _id: ObjectId('69861e680e6ea1f51160fe1c')
    }
  ],
  nModified: 15,
  ok: 1,
  '...': '...'
}

Specify Collation

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

Documents in the movies collection from the sample_mflix database have fields such as title and year.

The following operation uses collation to perform a case-insensitive search. The query searches for "the godfather" in lowercase, but with strength: 1 collation, the query matches "The Godfather" regardless of capitalization:

db.runCommand({
  update: "movies",
  updates: [
    {
      q: { title: "the godfather" },
      u: { $set: { featured: true } },
      collation: { locale: "en", strength: 1 }
    }
  ]
})

Specify arrayFilters for Array Update Operations

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

db.runCommand( {
   update: "movies",
   updates: [
      { q: { languages: "English" }, u: { $set: { "languages.$[element]" : "EN" } }, arrayFilters: [ { "element": "English" } ], multi: true}
   ]
} )

db.runCommand({
   update: "movies",
   updates: [
      { q: { cast: "Al Pacino" }, u: { $set: { "cast.$[elem]" : "REDACTED" } }, arrayFilters: [ { "elem": "Al Pacino" } ], multi: true }
   ]
})

Specify hint for Update Operations

Documents in the movies collection from the sample_mflix database have fields such as year and num_mflix_comments.

Create the following indexes on the collection:

[
   db.movies.createIndex( { year: 1 } ),
   db.movies.createIndex( { num_mflix_comments: 1 } )
]

The following update operation increments the num_mflix_comments field for "The Great Train Robbery" and explicitly hints to use the index { year: 1 }:

db.runCommand({
   update: "movies",
   updates: [
      { q: { title: "The Great Train Robbery" }, u: { $inc: { "num_mflix_comments": 1 } }, hint: { year: 1 }, multi: false }
   ]
})

To see the index used, you can run explain on an update operation. For example, the following explains an update that increments num_mflix_comments for movies with 5 or fewer comments released in 2000 or later:

db.runCommand(
   {
      explain: {
         update: "movies",
         updates: [ 
         { q: { "num_mflix_comments": { $lte: 5 }, "year": { $gte: 2000 } }, u: { $inc: { "num_mflix_comments": 1 } }, hint: { year: 1 }, multi: true }
         ]
      },
      verbosity: "queryPlanner"
   }
)

The explain does not modify the documents.

Use Variables in let Option or c Field

Variables can be defined in the let option or the c field and accessed in the updates array.

Documents in the movies collection from the sample_mflix database have fields such as title and year.

The following example uses the let option to define variables for finding and adding a new field to a movie.

db.runCommand( {
   update: "movies",
   updates: [
      { q: { $expr: { $eq: [ "$title", "$$movieTitle" ] } },
         u: [ { $set: { franchise: "$$franchiseName" } } ] }
   ],
   let : { movieTitle: "The Godfather", franchiseName: "The Godfather Trilogy" }
} )

The next example defines movieTitle and franchiseName variables in c and uses the variables to add a franchise field.

db.runCommand( {
   update: "movies",
   updates: [
      { q: { $expr: { $eq: [ "$title", "$$movieTitle" ] } },
         u: [ { $set: { franchise: "$$franchiseName" } } ],
         c: { movieTitle: "The Godfather", franchiseName: "The Godfather Trilogy" } }
      ]
} )

Update Operation with a Sort

Documents in the movies collection from the sample_mflix database have fields such as year, title, and num_mflix_comments.

The following example finds all movies from 1972 and updates the one with the most comments.

db.runCommand( {
   update: "movies",
   updates: [ {
      // Find movies from 1972
      q: { year: 1972 },
      // Add a classic_status field to the found movie
      u: { $set: { classic_status: "Most Discussed 1972 Film" } },
      // Only update one movie
      multi: false,
      // Sort movies by comment count in descending order
      sort: { num_mflix_comments: -1 }
   } ]
} )

The operation updates only the 1972 movie with the most comments.