update¶

On this page

Definition¶

update¶

New in version 2.6.

The update command modifies documents in a collection. A single update command can contain multiple update statements. The update methods provided by the MongoDB drivers use this command internally.

The update command has the following syntax:

{
   update: <collection>,
   updates:
      [
         { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean>, collation: <document> },
         { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean>, collation: <document> },
         { q: <query>, u: <update>, upsert: <boolean>, multi: <boolean>, collation: <document> },
         ...
      ],
   ordered: <boolean>,
   writeConcern: { <write concern> },
   bypassDocumentValidation: <boolean>
}

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 in the named collection.
`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`.
`writeConcern`	document	Optional. A document expressing the write concern of the `update` command. Omit to use the default 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.

Each element of the updates array contains the following fields:

Field	Type	Description
`q`	document	The query that matches documents to update. Use the same query selectors as used in the `find()` method.
`u`	document	The modifications to apply. For details, see Behavior.
`upsert`	boolean	Optional. If `true`, perform an insert if no documents match the query. If both `upsert` and `multi` are true and no documents match the query, the update operation inserts only a single document.
`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`.
`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.

Returns:	A document that contains the status of the operation. See Output for details.

Behavior¶

The <update> document can contain either all update operator expressions or all field:value expressions.

Update Operator Expressions¶

If the <update> document contains all update operator expressions, as in:

{
  $set: { status: "D" },
  $inc: { quantity: 2 }
}

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

`Field: Value` Expressions¶

If the <update> document contains only field:value expressions, as in:

{
  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.

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.

Examples¶

Update Specific Fields of One Document¶

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

For example, given a users collection, the following command uses the $set and $inc operators to modify the status and the points fields respectively of a document where the user equals "abc123":

db.runCommand(
   {
      update: "users",
      updates: [
         {
           q: { user: "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. See Output for details.

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

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, given a users collection, the following command uses the $set and $inc operators to modify the status and the points fields respectively of all documents in the collection:

db.runCommand(
   {
      update: "users",
      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. See Output for details.

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

Bulk Update¶

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

db.runCommand(
   {
      update: "users",
      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 } }
   ]
})

Output¶

The returned document contains a subset of the following fields:

update.ok¶: The status of the command.

update.n¶: The number of documents selected for update. If the 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.

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}."
      },
   ]
}

← resetError Query Plan Cache Commands →