update

On this page

Definition

Syntax
Access Control
Behavior
Examples
Output

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

Definition

update: The update command modifies documents in a collection. A single update command can contain multiple update statements.
Tip
In the mongo Shell, this command can also be run through the updateOne(), updateMany(), update(), replaceOne(), findOneAndReplace(), and findOneAndUpdate() helper methods.
Helper methods are convenient for mongo users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

Syntax

Changed in version 4.2.

The update command has the following syntax:

db.runCommand(
   {
      update: <collection>,
      updates: [
         {
           q: <query>,
           u: <document or pipeline>,
           upsert: <boolean>,
           multi: <boolean>,
           collation: <document>,
           arrayFilters: <array>,
           hint: <document|string>
         },
         ...
      ],
      ordered: <boolean>,
      maxTimeMS: <integer>,
      writeConcern: { <write concern> },
      bypassDocumentValidation: <boolean>,
      comment: <any>
   }
)

Command Fields

The command takes the following fields:

Field	Type	Description
`update`	string	The name of the target collection.
`updates`	array	An array of one or more update statements to perform on the named collection. For details of the update statements, see Update Statements.
`ordered`	boolean	Optional. If `true`, then when an update statement fails, return without performing the remaining update statements. If `false`, then when an update fails, continue with the remaining update statements, if any. Defaults to `true`.
`maxTimeMS`	non-negative integer	Optional. Specifies a time limit in milliseconds. If you do not specify a value for `maxTimeMS`, operations will not time out. A value of `0` explicitly specifies the default unbounded behavior. MongoDB terminates operations that exceed their allotted time limit using the same mechanism as `db.killOp()`. MongoDB only terminates an operation at one of its designated interrupt points.
`writeConcern`	document	Optional. A document expressing the write concern of the `update` command. Omit to use the default write concern. Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.
`bypassDocumentValidation`	boolean	Optional. Enables `update` to bypass document validation during the operation. This lets you update documents that do not meet the validation requirements. New in version 3.2.
`comment`	any	Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: mongod log messages, in the `attr.command.cursor.comment` field. Database profiler output, in the `command.comment` field. `currentOp` output, in the `command.comment` field. A comment can be any valid BSON type (string, integer, object, array, etc). New in version 4.4.

Update Statements

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

Field

Type

Description

document

The query that matches documents to update. Use the same query selectors as used in the find() method.

document or pipeline

The modifications to apply.

The value can be either:

A document that contains update operator expressions,
A replacement document with only <field1>: <value1> pairs, or
Starting in MongoDB 4.2, an aggregation pipeline.
- $addFields and its alias $set
- $project and its alias $unset
- $replaceRoot and its alias $replaceWith.

For details, see Behavior.

upsert

boolean

Optional. When true, update either:

Creates a new document if no documents match the query. For more details see upsert behavior.
Updates a single document that matches the query.

If both upsert and multi are true and no documents match the query, the update operation inserts only a single document.

To avoid multiple upserts, ensure that the query field(s) are uniquely indexed. See Upsert with Unique Index for an example.

Defaults to false, which does not insert a new document when no match is found.

multi

boolean

Optional. If true, updates all documents that meet the query criteria. If false, limit the update to one document that meet the query criteria. Defaults to false.

When updating multiple documents, if a single document fails to update, further documents are not updated. See multi-update failures for more details on this behavior.

collation

document

Optional.

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.

New in version 3.4.

arrayFilters

array

Optional. An array of filter documents that determines which array elements to modify for an update operation on an array field.

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.

Note

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. For example, if the update statement includes the identifier x (possibly multiple times), you cannot specify the following for arrayFilters that includes 2 separate filter documents for x:

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

However, you can specify compound conditions on the same identifier in a single filter document, such as in the following examples:

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

For examples, see Specify arrayFilters for Array Update Operations.

New in version 3.6.

hint

Document or string

Optional. A document or string that specifies the index to use to support the query predicate.

The option can take an index specification document or the index name string.

If you specify an index that does not exist, the operation errors.

For an example, see Specify hint for Update Operations.

New in version 4.2.

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.

Access Control

On deployments running with authorization, the user must have access that includes the following privileges:

update action on the specified collection(s).
find action on the specified collection(s).
insert action on the specified collection(s).

The built-in role readWrite provides the required privileges.

Behavior

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, create a members collection with the following documents:

db.members.insertMany( [
   { "_id" : 1, "member" : "Taylor", "status" : "pending", "points" : 1},
   { "_id" : 2, "member" : "Alexis", "status" : "enrolled", "points" : 59},
   { "_id" : 3, "member" : "Elizabeth", "status" : "enrolled", "points" : 34}
] )

The following operation creates a document validator on the members collection with a rule that the points value can not equal 60.

db.runCommand( {
   collMod: "members",
   validator: { points: { $ne: 60 } }
} )

This update command increases the points field of every document by 1.

db.runCommand(
 {
    update: "members",
    updates: [
     {
         q: {},
         u: { $inc: { points: 1 } },
         multi: true
     }
    ]
 }
)

After running the command, the collection contains the following documents:

{ _id: 1, member: 'Taylor', status: 'A', points: 2 }
{ _id: 2, member: 'Alexis', status: 'D', points: 59 }
{ _id: 3, member: 'Elizabeth', status: 'C', points: 34 }

The update command updated the points value of the first document but failed to update the second document because of the validator rule that the points value can not equal 60. The third document did not update because no further documents update following a write error.

Tip

Update with an Aggregation Pipeline

Starting in MongoDB 4.2, 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" ] }
      ],
      ...
   },
   ...
]

Note

The $set and $unset used in the pipeline refers to the aggregation stages $set and $unset respectively, and not the update operators $set and $unset.

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.

Unique Index Key Pattern

Update Operation

Result

{ name : 1 }

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

The score field of the matched document is incremented by 1.

{ name : 1 }

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

The operation fails because it modifies the field in the unique index key pattern (name).

{ name : 1 }

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

The operation fails because the equality predicate fields (name, email) do not match the index key field (name).

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.

Document Validation

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

Sharded Collections

`upsert` on a Sharded Collection

To use update with multi: false on a sharded collection,

If you do not specify upsert: true, the filter q must either include an equality match on the _id field or target a single shard (such as by including the shard key).
If you specify upsert: true, the filter q must include an equality match on the shard key.
However, starting in version 4.4, documents in a sharded collection can be missing the shard key fields. To target a document that is missing the shard key, you can use the null equality match in conjunction with another filter condition (such as on the _id field). For example:
```
{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key
```

Replace Document

Starting in MongoDB 4.2, when replacing a document, update attempts to target a shard, first by using the query filter. If the operation cannot target a single shard by the query filter, it then attempts to target by the replacement document.

In earlier versions, the operation attempts to target using the replacement document.

Shard Key Modification

Starting in MongoDB 4.2, you can update a document's shard key value unless the shard key field is the immutable _id field. Before MongoDB 4.2, a document's shard key field value is immutable.

To modify the existing shard key value with update:

You must run on a mongos. Do not issue the operation directly on the shard.
You must run either in a transaction or as a retryable write.
You must specify multi: false.
You must include an equality query filter on the full shard key.

Tip

Since a missing key value is returned as part of a null equality match, to avoid updating a null-valued key, include additional query conditions (such as on the _id field) as appropriate.

Missing Shard Key

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. To use update to set the document's missing shard key, you must run on a mongos. Do not issue the operation directly on the shard.

In addition, the following requirements also apply:

Task	Requirements
To set to `null`	Can specify `multi: true`. Requires equality filter on the full shard key if `upsert: true` is specified.
To set to a non-`null` value:	Must be performed either inside a transaction or as a retryable write. Must specify `multi: false`. Requires equality filter on the full shard key if either: `upsert: true`, or if using a replacement document and the new shard key value belongs to a different shard.

Tip

Since a missing key value is returned as part of a null equality match, to avoid updating a null-valued key, include additional query conditions (such as on the _id field) as appropriate.

Transactions

update can be used inside distributed transactions.

Important

In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for distributed transactions.

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.

Upsert within Transactions

You can create collections and indexes inside a distributed transaction if the transaction is not a cross-shard write transaction.

update with upsert: true can be run on an existing collection or a non-existing collection. If run on a non-existing collection, the operation creates the collection.

Tip

Examples

Update Specific Fields of One Document

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

For example, create a members collection with the following documents:

db.members.insertMany([
   { _id: 1, member: "abc123", status: "Pending", points: 0, misc1: "note to self: confirm status", misc2: "Need to activate" },
   { _id: 2, member: "xyz123", status: "D", points: 59, misc1: "reminder: ping me at 100pts", misc2: "Some random comment" },
])

The following command uses the $set and $inc update operators to update the status and the points fields of a document where the member equals "abc123":

db.runCommand(
   {
      update: "members",
      updates: [
         {
           q: { member: "abc123" }, u: { $set: { status: "A" }, $inc: { points: 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.

The returned document shows that the command found and updated a single document. The command returns:

{ "n" : 1, "nModified" : 1, "ok" : 1, <additional fields if run on a replica set/sharded cluster> }

See Output for details.

After the command, the collection contains the following documents:

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 1, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "D", "points" : 59, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

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, a members collection contains the following documents:

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 1, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "D", "points" : 59, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

The following command uses the $set and $inc update operators to modify the status and the points fields respectively of all documents in the collection:

db.runCommand(
   {
      update: "members",
      updates: [
         { q: { }, u: { $set: { status: "A" }, $inc: { points: 1 } }, multi: true }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The update modifies all documents that match the query specified in the q field, namely the empty query which matches all documents in the collection.

The returned document shows that the command found and updated multiple documents. For a replica set, the command returns:

{ "n" : 2, "nModified" : 2, "ok" : 1,  <additional fields if run on a replica set/sharded cluster> }

See Output for details.

After the command, the collection contains the following documents:

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 2, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

Update with Aggregation Pipeline

Starting in MongoDB 4.2, 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.

Example 1

The following examples uses the aggregation pipeline to modify a field using the values of the other fields in the document.

A members collection contains the following documents:

{ "_id" : 1, "member" : "abc123", "status" : "A", "points" : 2, "misc1" : "note to self: confirm status", "misc2" : "Need to activate" }
{ "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }

Assume that instead of separate misc1 and misc2 fields, you want to gather these into a new comments field. The following update operation uses an aggregation pipeline to add the new comments field and remove the misc1 and misc2 fields for all documents in the collection.

First, set the status field to "Modified" and add a new field comments that contains the current contents of two other fields misc1 and misc2 fields.
Second, remove the misc1 and misc2 fields.

db.runCommand(
   {
      update: "members",
      updates: [
         {
           q: { },
           u: [
              { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
              { $unset: [ "misc1", "misc2" ] }
           ],
           multi: true
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Note

The $set and $unset used in the pipeline refers to the aggregation stages $set and $unset respectively, and not the update operators $set and $unset.

The returned document shows that the command found and updated multiple documents. The command returns:

{ "n" : 2, "nModified" : 2, "ok" : 1, <additional fields if run on a replica set/sharded cluster> }

See Output for details.

After the command, the collection contains the following documents:

{ "_id" : 1, "member" : "abc123", "status" : "Modified", "points" : 2, "comments" : [ "note to self: confirm status", "Need to activate" ] }
{ "_id" : 2, "member" : "xyz123", "status" : "Modified", "points" : 60, "comments" : [ "reminder: ping me at 100pts", "Some random comment" ] }

Example 2

The aggregation pipeline allows the update to perform conditional updates based on the current field values as well as use current field values to calculate a separate field value.

db.students.insert([
   { "_id" : 1, "tests" : [ 95, 92, 90 ] },
   { "_id" : 2, "tests" : [ 94, 88, 90 ] },
   { "_id" : 3, "tests" : [ 70, 75, 82 ] }
]);

Using an aggregation pipeline, you can update the documents with the calculated grade average and letter grade.

db.runCommand(
   {
      update: "students",
      updates: [
         {
           q: { },
           u: [
                 { $set: { average : { $avg: "$tests" } } },
                 { $set: { grade: { $switch: {
                                       branches: [
                                           { case: { $gte: [ "$average", 90 ] }, then: "A" },
                                           { case: { $gte: [ "$average", 80 ] }, then: "B" },
                                           { case: { $gte: [ "$average", 70 ] }, then: "C" },
                                           { case: { $gte: [ "$average", 60 ] }, then: "D" }
                                       ],
                                       default: "F"
                 } } } }
           ],
           multi: true
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

Note

The $set used in the pipeline refers to the aggregation stage $set, and not the update operators $set.

First Stage: The $set stage calculates a new field average based on the average of the tests field. See $avg for more information on the $avg aggregation operator.
Second Stage: The $set stage calculates a new field grade based on the average field calculated in the previous stage. See $switch for more information on the $switch aggregation operator.

The returned document shows that the command found and updated multiple documents. The command returns:

{ "n" : 3, "nModified" : 3, "ok" : 1, <additional fields if run on a replica set/sharded cluster> }

After the command, the collection contains the following documents:

{ "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92.33333333333333, "grade" : "A" }
{ "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 90.66666666666667, "grade" : "A" }
{ "_id" : 3, "tests" : [ 70, 75, 82 ], "average" : 75.66666666666667, "grade" : "C" }

Bulk Update

The following example performs multiple update operations on the members collection:

db.runCommand(
   {
      update: "members",
      updates: [
         { q: { status: "P" }, u: { $set: { status: "D" } }, multi: true },
         { q: { _id: 5 }, u: { _id: 5, name: "abc123", status: "A" }, upsert: true }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

The returned document shows that the command modified 10 documents and inserted a document with the _id value 5. See Output for details.

{
   "ok" : 1,
   "nModified" : 10,
   "n" : 11,
   "upserted" : [
      {
         "index" : 1,
         "_id" : 5
      }
   ]
}

Specify Collation

New in version 3.4.

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

A collection myColl has the following documents:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

The following operation includes the collation option:

db.runCommand({
   update: "myColl",
   updates: [
     { q: { category: "cafe", status: "a" }, u: { $set: { status: "Updated" } }, collation: { locale: "fr", strength: 1 } }
   ]
})

Specify `arrayFilters` for Array Update Operations

New in version 3.6.

Starting in MongoDB 3.6, when updating an array field, you can specify arrayFilters that determine which array elements to update.

Update Elements Match `arrayFilters` Criteria

Create a collection students with the following documents:

db.students.insert([
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
]);

To modify all elements that are greater than or equal to 100 in the grades array, use the filtered positional operator $[<identifier>] with the arrayFilters option:

db.runCommand({
   update: "students",
   updates: [
     { q: { grades: { $gte: 100 } }, u: { $set: { "grades.$[element]" : 100 } }, arrayFilters: [ { "element": { $gte: 100 } } ], multi: true}
   ]
})

After the operation, the collection contains the following documents:

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 100, 100 ] }

Update Specific Elements of an Array of Documents

Create a collection students2 with the following documents:

db.students2.insert([
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
]);

To modify the value of the mean field for all elements in the grades array where the grade is greater than or equal to 85, use the filtered positional operator $[<identifier>] with the arrayFilters:

db.runCommand({
   update: "students2",
   updates: [
     { q: { }, u: { $set: { "grades.$[elem].mean" : 100 } }, arrayFilters: [ { "elem.grade": { $gte: 85 } } ], multi: true }
   ]
})

After the operation, the collection has the following documents:

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
   ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 100, "std" : 6 },
      { "grade" : 87, "mean" : 100, "std" : 3 },
      { "grade" : 85, "mean" : 100, "std" : 4 }
   ]
}

Specify `hint` for Update Operations

New in version 4.2.

Create a sample members collection with the following documents:

db.members.insertMany([
   { "_id" : 1, "member" : "abc123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" },
   { "_id" : 3, "member" : "lmn123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20,  "misc1" : "Deactivated", "misc2" : null },
   { "_id" : 5, "member" : "ijk123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }
])

Create the following indexes on the collection:

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

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

Note

If you specify an index that does not exist, the operation errors.

db.runCommand({
   update: "members",
   updates: [
     { q: { "points": { $lte: 20 }, "status": "P" }, u: { $set: { "misc1": "Need to activate" } }, hint: { status: 1 }, multi: true }
   ]
})

The update command returns the following:

{ "n" : 3, "nModified" : 3, "ok" : 1 }

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

db.runCommand(
   {
     explain: {
       update: "members",
       updates: [
         { q: { "points": { $lte: 20 }, "status": "P" }, u: { $set: { "misc1": "Need to activate" } }, hint: { status: 1 }, multi: true }
       ]
     },
     verbosity: "queryPlanner"
   }
)

The explain does not modify the documents.

Output

The returned document contains a subset of the following fields:

update.ok: The status of the command.

update.n

An update command accepts an array of document updates, some of which can be upserts. For an update, n is the number of documents selected for the update. For an upsert, n is 1 for the inserted document. The server adds the n values for all the updates and upserts and returns the total as update.n.

If an update operation results in no change to the document, e.g. $set expression updates the value to the current value, n can be greater than nModified.

update.nModified: The number of documents updated. If the update operation results in no change to the document, such as setting the value of the field to its current value, nModified can be less than n.

update.upserted

An array of documents that contains information for each document inserted through the update with upsert: true.

Each document contains the following information:

update.upserted.index: An integer that identifies the update with upsert:true statement in the updates array, which uses a zero-based index.

update.upserted._id: The _id value of the added document.

update.writeErrors

An array of documents that contains information regarding any error encountered during the update operation. The writeErrors array contains an error document for each update statement that errors.

Each error document contains the following fields:

update.writeErrors.index: An integer that identifies the update statement in the updates array, which uses a zero-based index.

update.writeErrors.code: An integer value identifying the error.

update.writeErrors.errmsg: A description of the error.

update.writeConcernError

Document that describe error related to write concern and contains the field:

update.writeConcernError.code: An integer value identifying the cause of the write concern error.

update.writeConcernError.errmsg: A description of the cause of the write concern error.

update.writeConcernError.errInfo.writeConcern

New in version 4.4.

The write concern object used for the corresponding operation. For information on write concern object fields, see Write Concern Specification.

The write concern object may also contain the following field, indicating the source of the write concern:

update.writeConcernError.errInfo.writeConcern.provenance

A string value indicating where the write concern originated (known as write concern provenance). The following table shows the possible values for this field and their significance:

Provenance	Description
`clientSupplied`	The write concern was specified in the application.
`customDefault`	The write concern originated from a custom defined default value. See `setDefaultRWConcern`.
`getLastErrorDefaults`	The write concern originated from the replica set's `settings.getLastErrorDefaults` field.
`implicitDefault`	The write concern originated from the server in absence of all other write concern specifications.

In addition to the aforementioned update specific return fields, the db.runCommand() includes additional information:

for replica sets: optime, electionId, $clusterTime, and operationTime.
for sharded clusters: operationTime and $clusterTime.

See db.runCommand Response for details on these fields.

The following is an example document returned for a successful update command that performed an upsert:

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

The following is an example document returned for a bulk update involving three update statements, where one update statement was successful and two other update statements encountered errors:

{
   "ok" : 1,
   "nModified" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 16837,
         "errmsg" : "The _id field cannot be changed from {_id: 1.0} to {_id: 5.0}."
      },
      {
         "index" : 2,
         "code" : 16837,
         "errmsg" : "The _id field cannot be changed from {_id: 2.0} to {_id: 6.0}."
      },
   ]
}

Back

resetError

Query Plan Cache Commands

Definition

Tip

Syntax

Command Fields

Update Statements

Note

Returns

Access Control

Behavior

Update with an Update Operator Expressions Document

Update with a Replacement Document

Multi-Update Failures

Tip

See also:

Update with an Aggregation Pipeline

Note

Upsert with Unique Index

Limits

Document Validation

Sharded Collections

upsert on a Sharded Collection

Replace Document

Shard Key Modification

Tip

Missing Shard Key

Tip

Transactions

Important

Upsert within Transactions

Tip

See also:

Write Concerns and Transactions

Examples

Update Specific Fields of One Document

Update Specific Fields of Multiple Documents

Update with Aggregation Pipeline

Example 1

Note

Example 2

Note

Bulk Update

Specify Collation

Specify arrayFilters for Array Update Operations

Update Elements Match arrayFilters Criteria

Update Specific Elements of an Array of Documents

Specify hint for Update Operations

Note

Output

`upsert` on a Sharded Collection

Specify `arrayFilters` for Array Update Operations

Update Elements Match `arrayFilters` Criteria

Specify `hint` for Update Operations