- Reference >
- Database Commands >
- Query and Write Operation Commands >
- update
update¶
On this page
Definition¶
-
update
¶ New in version 2.6.
The
update
command modifies documents in a collection. A singleupdate
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: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. Iffalse
, then when an update fails, continue with the remaining update statements, if any. Defaults totrue
.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 Read Concern/Write Concern/Read Preference.
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 bothupsert
andmulti
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. Iffalse
, limit the update to one document that meet the query criteria. Defaults tofalse
.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:
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 identifierx
(possibly multiple times), you cannot specify the following forarrayFilters
that includes 2 separate filter documents forx
:However, you can specify compound conditions on the same identifier in a single filter document, such as in the following examples:
For examples, see Specify arrayFilters for Array Update Operations.
New in version 3.6.
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:
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:
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.
Transactions¶
update
supports multi-document transactions.
If the operation results in an upsert, the collection must already exist.
Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Read Concern/Write Concern/Read Preference.
Important
In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transaction 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 multi-document transactions. For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.
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"
:
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.
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:
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.
Bulk Update¶
The following example performs multiple update operations on the
users
collection:
The returned document shows that the command modified 10
documents
and inserted a document with the _id
value 5
. See
Output for details.
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:
The following operation includes the collation option:
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:
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:
After the operation, the collection contains the following documents:
Update Specific Elements of an Array of Documents¶
Create a collection students2
with the following documents:
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
:
After the operation, the collection has the following documents:
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 thannModified
.
-
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 thann
.
-
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 theupdates
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:
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: