db.collection.update() (mongosh method)

Parameters

The db.collection.update() method takes the following parameters:

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

Returns

The method returns a WriteResult document that contains the status of the operation.

Limitations

If you set multi: true, use the update() method only for idempotent operations.

Using $expr in an Update with Upsert

Attempting to use the $expr operator with the upsert flag set to true will generate an error.

Sharded Collections

To use db.collection.update() with multi: false on a sharded collection, you must include an exact match on the _id field or target a single shard (such as by including the shard key).

When the db.collection.update() performs update operations (and not document replacement operations), db.collection.update() can target multiple shards.

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Transactions

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

Oplog Entries

If a db.collection.update() operation successfully updates one or more documents, the operation adds an entry on the oplog (operations log). If the operation fails or does not find any documents to update, the operation does not add an entry on the oplog.

Upsert with Dotted _id Query

When you execute an update() with upsert: true and the query matches no existing document, MongoDB will refuse to insert a new document if the query specifies conditions on the _id field using dot notation.

This restriction ensures that the order of fields embedded in the _id document is well-defined and not bound to the order specified in the query.

If you attempt to insert a document in this way, MongoDB raises an error.

Upsert with Duplicate Values

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

If all db.collection.update() operations finish the query phase before any client successfully inserts data, and there is no unique index on the name field, each db.collection.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 db.collection.update() operations now exhibit the following behavior:

• Exactly one db.collection.update() operation will successfully insert a new

  document.

• Other db.collection.update() operations either update the newly-inserted

  document or fail due to a unique key collision.

  In order for other db.collection.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.

Array Update Operations

In the update document, use the $[<identifier>] filtered positional operator to define an identifier, which you then reference in the array filter documents. You cannot have an array filter document for an identifier if the identifier is not included in the update document.

The <identifier> must begin with a lowercase letter and contain only alphanumeric characters.

You can include the same identifier multiple times in the update document; however, for each distinct identifier ($[identifier]) in the update document, you must specify exactly one corresponding array filter document. That is, you cannot specify multiple array filter documents for the same identifier. However, you can specify compound conditions on the same identifier in a single filter document

Successful Results

The db.collection.update() method returns a WriteResult() object that contains the status of the operation. Upon success, the WriteResult() object contains the number of documents that matched the query condition, the number of documents inserted by the update, and the number of documents modified.

Write Concern Errors

If the db.collection.update() method encounters write concern errors, the results include the WriteResult.writeConcernError field.

The following table explains the possible values of WriteResult.writeConcernError.provenance:

Errors Unrelated to Write Concern

If the db.collection.update() method encounters a non-write concern error, the results include the WriteResult.writeError field.

Insert a New Document if No Match Exists (Upsert)

When you specify the option upsert: true:

• If document(s) match the query criteria, db.collection.update() performs an update.

• If no document matches the query criteria, db.collection.update() inserts a single document.

  Note

  If multiple, identical upserts are issued at roughly the same time, it is possible for update() used with upsert: true to create duplicate documents. See Upsert with Duplicate Values for more information.

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

The following tabs showcase a variety of uses of the upsert modifier with update().

db.movies.update(
   { title: "Test Movie 12345" },
   { 
      $set: {
         title: "Test Movie 12345", 
         year: 2024, 
         genres: [ "Documentary" ],
         rated: "NR"
      }
   },
   { upsert: true }
)

db.movies.update(
   { title: "Test Movie 67890" },   // Query parameter
   {                                // Update document
      $set: { rated: "PG" },
      $setOnInsert: { year: 2024, type: "movie" }
   },
   { upsert: true }                 // Options
)

db.movies.update(
   { title: "Test Movie ABC123" },  // Query parameter
   [                                // Aggregation pipeline
      { $set: { 
         year: 2024, 
         type: "movie",
         rated: "NR",
         lastModified: "$$NOW" 
      } }
   ],
   { upsert: true }   // Options
)

db.movies.update(
   { title: { $in: ["The Godfather", "The Matrix"] } },
   { $set: { test_upsert_field: true } },
   { upsert: true, multi: true }
)

db.movies.update(
   { "title": "Test Movie Unique789" },
   { $set: { year: 2024, type: "movie" } },
   { upsert: true, multi: true }
)

Update with Aggregation Pipeline

The db.collection.update() 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).

db.movies.update(
   { title: "The Godfather" },
   [
      { $set: { 
            displayTitle: { $concat: [ "$title", " (", { $toString: "$year" }, ")" ] },
            lastModified: "$$NOW" 
         } 
      }
   ]
)

db.movies.update(
   { 
      year: 2015,
      "imdb.rating": { $type: "number" },
      "tomatoes.viewer.rating": { $type: "number" }
   },
   [
      { $set: { 
         combinedScore: { 
            $round: [ 
               { $avg: [ 
               { $multiply: [ "$imdb.rating", 10 ] }, 
               { $multiply: [ "$tomatoes.viewer.rating", 10 ] } 
               ] }, 
               1 
            ] 
         }, 
         lastUpdate: "$$NOW" 
         } 
      },
      { $set: { 
         grade: { 
            $switch: {
               branches: [
               { case: { $gte: [ "$combinedScore", 80 ] }, then: "A" },
               { case: { $gte: [ "$combinedScore", 70 ] }, then: "B" },
               { case: { $gte: [ "$combinedScore", 60 ] }, then: "C" },
               { case: { $gte: [ "$combinedScore", 50 ] }, then: "D" }
               ],
               default: "F"
            } 
         } 
         } 
      }
   ],
   { multi: true }
)

Specify arrayFilters for Array Update Operations

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

db.movies.update(
   { title: "The Godfather" },
   { $set: { "writers.$[elem]" : { $concat: [ "$elem", " - UPDATED" ] } } },
   {
      arrayFilters: [ { "elem": { $regex: /screenplay/ } } ]
   }
)

Specify hint for Update Operations

The hint option allows you to specify which index MongoDB should use for the update operation. This is useful when updating multiple documents and you want to ensure a specific index is used for performance. This example uses the existing movies collection from the sample_mflix database.

First, create an index on the year field:

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

The following update operation explicitly hints to use the { year: 1 } index to update all movies from 2010-2015:

db.movies.update(
   { year: { $gte: 2010, $lte: 2015 } },  // Query parameter
   { $set: { decade: "2010s" } },             // Update document
   { multi: true, hint: { year: 1 } }          // Options
)

To see the index used, run explain on the operation:

db.movies.explain().update(
   { title: "The Godfather", year: { $gte: 1970 } },
   { $set: { test_hint_field: true } },
   { hint: { year: 1 } }
)

The db.collection.explain().update() does not modify the documents.

Use Variables in let

To define variables that you can access elsewhere in the command, use the let option.

The example:

• Defines two variables in the let option: targetTitle (set to "The Matrix") and newTitle (set to "The Matrix Reloaded")

• Uses $expr in the query filter to compare the document's title field against the $$targetTitle variable

• Uses an aggregation pipeline with $set to update the title field to the value of $$newTitle

db.movies.update(
   { $expr: { $eq: [ "$title", "$$targetTitle" ] } },
   [ { $set: { sequel: "$$sequelTitle" } } ],
   { let : { targetTitle: "The Matrix", sequelTitle: "The Matrix Reloaded" } }
)

Override Default Write Concern

The following operation to a replica set specifies a write concern of w: 2 with a wtimeout of 5000 milliseconds. This operation either returns after the write propagates to both the primary and one secondary, or times out after 5 seconds.

db.movies.update(
   { num_mflix_comments: { $lte: 10 } },
   { $set: { featured: true } },
   {
      multi: true,
      writeConcern: { w: 2, j: true, wtimeout: 5000 }
   }
)

The operation successfully completes after the write is acknowledged by the primary and at least one secondary, as specified by w: 2.

Write Concern Errors in Sharded Clusters

When db.collection.update() 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.update() 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.

Specify Collation

Specifies the collation to use for the operation.

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

The collation option has the following syntax:

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

When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.

If the collation is unspecified but the collection has a default collation (see db.createCollection()), the operation uses the collation specified for the collection.

If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons.

You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort.

This operation updates all movies with titles that start with night and uses strength: 1 for case-insensitive comparison:

db.movies.update(
   { title: /^night/i },
   { $set: { updated: true } },
   {
      collation: { locale: "en", strength: 1 },
      multi: true
   }
)