update
Definition
update
The
update
command modifies documents in a collection. A singleupdate
command can contain multiple update statements.Tip
In
mongosh
, this command can also be run through theupdateOne()
,updateMany()
,replaceOne()
,findOneAndReplace()
, andfindOneAndUpdate()
helper methods.Helper methods are convenient for
mongosh
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 5.0.
The update
command has the following syntax:
db.runCommand( { update: <collection>, updates: [ { q: <query>, u: <document or pipeline>, c: <document>, // Added in MongoDB 5.0 upsert: <boolean>, multi: <boolean>, collation: <document>, arrayFilters: <array>, hint: <document|string> }, ... ], ordered: <boolean>, maxTimeMS: <integer>, writeConcern: { <write concern> }, bypassDocumentValidation: <boolean>, comment: <any>, let: <document> // Added in MongoDB 5.0 } )
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 MongoDB terminates operations that exceed their allotted time limit
using the same mechanism as | |||||
writeConcern | document | Optional. A document expressing the write concern
of the 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. | |||||
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:
A comment can be any valid BSON type (string, integer, object, array, etc). | |||||
document | Optional. Specifies a document with a list of variables. This allows you to improve command readability by separating the variables from the query text. The document syntax is:
The variable is set to the value returned by the expression, and cannot be changed afterwards. To access the value of a variable in the command, use the double
dollar sign prefix ( For a complete example, see Use Variables in New in version 5.0. |
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 | |||||||||||||||||||
document or pipeline | The modifications to apply. The value can be either:
For details, see Behavior. | |||||||||||||||||||
document | Optional. You can specify Specifies a document with a list of variables. This allows you to improve command readability by separating the variables from the query text. The document syntax is:
The variable is set to the value returned by the expression, and cannot be changed afterwards. To access the value of a variable in the command, use the double
dollar sign prefix ( NoteTo use a variable to filter results, you must access the variable
within the For a complete example using New in version 5.0. | |||||||||||||||||||
boolean | Optional. When
If both To avoid multiple upserts, ensure that the
Defaults to | |||||||||||||||||||
multi | boolean | Optional. If 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:
When specifying collation, the If the collation is unspecified but the collection has a
default collation (see 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 NoteThe You can include the same identifier multiple times in the update
document; however, for each distinct identifier (
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 New in version 3.6. | ||||||||||||||||||
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 |
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.
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
$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
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
ormulti
isfalse
.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 | ||||||
---|---|---|---|---|---|---|---|---|
|
| The score field of the matched document is incremented by
1. | ||||||
|
| The operation fails because it modifies the field in the
unique index key pattern ( name ). | ||||||
|
| 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, 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
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.
Shard Key Modification
You can update a document's shard key value unless the shard key field is the
immutable _id
field.
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.
See also upsert
on a Sharded Collection.
Missing Shard Key
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 |
|
To set to a non- null value: |
|
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.
See also:
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.
Write Concerns and Transactions
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.
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
The update
command can use an aggregation pipeline for the update.
The pipeline can consist of the following stages:
$addFields
and its alias$set
$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).
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 fieldcomments
that contains the current contents of two other fieldsmisc1
andmisc2
fields.Second, remove the
misc1
andmisc2
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 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.insertMany( [ { "_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
- First Stage
- The
$set
stage calculates a new fieldaverage
based on the average of thetests
field. See$avg
for more information on the$avg
aggregation operator. - Second Stage
- The
$set
stage calculates a new fieldgrade
based on theaverage
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
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.insertMany( [ { "_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.insertMany( [ { "_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
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.
Use Variables in let
Option or c
Field
New in version 5.0.
Variables can be defined in the let option or
the c field and accessed in the updates
array.
Note
To filter results using a variable, you must access the variable
within the $expr
operator.
Create a collection cakeFlavors
:
db.cakeFlavors.insertMany( [ { _id: 1, flavor: "chocolate" }, { _id: 2, flavor: "strawberry" }, { _id: 3, flavor: "cherry" } ] )
The following example defines targetFlavor
and newFlavor
variables in let
and uses the variables to change the cake flavor
from cherry to orange:
db.runCommand( { update: db.cakeFlavors.getName(), updates: [ { q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } }, u: [ { $set: { flavor: "$$newFlavor" } } ] } ], let : { targetFlavor: "cherry", newFlavor: "orange" } } )
The next example defines targetFlavor
and newFlavor
variables in
c
and uses the variables to change the cake flavor from chocolate to
vanilla:
db.runCommand( { update: db.cakeFlavors.getName(), updates: [ { q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } }, u: [ { $set: { flavor: "$$newFlavor" } } ], c: { targetFlavor: "chocolate", newFlavor: "vanilla" } } ] } )
Output
The returned document contains a subset of the following fields:
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
is1
for the inserted document. The server adds then
values for all the updates and upserts and returns the total asupdate.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 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.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.writeConcernError
Document that describe error related to write concern and contains the field:
update.writeConcernError.errInfo.writeConcern
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:ProvenanceDescriptionclientSupplied
The write concern was specified in the application.customDefault
The write concern originated from a custom defined default value. SeesetDefaultRWConcern
.getLastErrorDefaults
The write concern originated from the replica set'ssettings.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
, andoperationTime
.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}." }, ] }