- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.update()
db.collection.update()¶
On this page
Definition¶
-
db.collection.
update
(query, update, options)¶ Modifies an existing document or documents in a collection. The method can modify specific fields of an existing document or documents or replace an existing document entirely, depending on the update parameter.
By default, the
update()
method updates a single document. Set the Multi Parameter to update all documents that match the query criteria.The
update()
method has the following form:Changed in version 2.6.
The
update()
method takes the following parameters:Parameter Type Description query
document The selection criteria for the update. Use the same query selectors as used in the find()
method.update
document The modifications to apply. For details see Update Parameter. upsert
boolean Optional. If set to true
, creates a new document when no document matches the query criteria. The default value isfalse
, which does not insert a new document when no match is found.multi
boolean Optional. If set to true
, updates multiple documents that meet thequery
criteria. If set tofalse
, updates one document. The default value isfalse
. For additional information, see Multi Parameter.writeConcern
document Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.
New in version 2.6.
Changed in version 2.6: The
update()
method returns an object that contains the status of the operation.Returns: A WriteResult object that contains the status of the operation.
Behavior¶
Safe Writes¶
Changed in version 2.6.
The update()
method uses the
update
command, which uses the default write concern. To
specify a different write concern, include the writeConcern
option
in the options parameter. See Override Default Write Concern for
an example.
Update Parameter¶
The update()
method either modifies specific
fields in existing documents or replaces an existing document entirely.
Update Specific Fields¶
If the <update>
document contains update operator modifiers, such as those using the
$set
modifier, then:
- The
<update>
document must contain only update operator expressions. - The
update()
method updates only the corresponding fields in the document.
To update an embedded document or an array as a whole, specify the replacement value for the field. To update particular fields in an embedded document or in an array, use dot notation to specify the field.
Replace a Document Entirely¶
If the <update>
document contains only field:value
expressions, then:
- The
update()
method replaces the matching document with the<update>
document. Theupdate()
method does not replace the_id
value. For an example, see Replace All Fields. update()
cannot update multiple documents.
Upsert Option¶
Upsert Behavior¶
If upsert
is true
and no document matches the query
criteria, update()
inserts a single document.
The update creates the new document with either:
- The fields and values of the
<update>
parameter if the<update>
parameter contains only field and value pairs, or - The fields and values of both the
<query>
and<update>
parameters if the<update>
parameter contains update operator expressions. The update creates a base document from the equality clauses in the<query>
parameter, and then applies the update expressions from the<update>
parameter.
If upsert
is true
and there are documents that match the query
criteria, update()
performs an update.
See also
Use Unique Indexes¶
Warning
To avoid inserting the same document more than once,
only use upsert: true
if the query
field is uniquely
indexed.
Given a collection named people
where no documents have a name
field that holds the value Andy
. Consider when multiple clients
issue the following update with upsert: true
at the same
time:
If all update()
operations complete the
query
portion before any client successfully inserts data, and
there is no unique index on the name
field, then each update
operation may result in an insert.
To prevent MongoDB from inserting the same document more than once,
create a unique index on the name
field.
With a unique index, if multiple applications issue the same update
with upsert: true
, exactly one
update()
would successfully insert a new
document.
The remaining operations would either:
update the newly inserted document, or
fail when they attempted to insert a duplicate.
If the operation fails because of a duplicate index key error, applications may retry the operation which will succeed as an update operation.
Multi Parameter¶
If multi
is set to true
, the update()
method updates all documents that meet the <query>
criteria. The
multi
update operation may interleave with other operations, both
read and/or write operations. For unsharded collections, you can
override this behavior with the $isolated
operator, which
isolates the update operation and disallows yielding during the
operation. This isolates the update so that no client can see the
updated documents until they are all processed, or an error stops the
update operation.
If the <update> document contains only
field:value
expressions, then update()
cannot update multiple documents.
For an example, see Update Multiple Documents.
Sharded Collections¶
All update()
operations for a sharded
collection that specify the multi: false
option must include the
shard key or the _id
field in the query
specification. update()
operations
specifying multi: false
in a sharded collection without the shard key or
the _id
field return an error.
See also
Examples¶
Update Specific Fields¶
To update specific fields in a document, use update operators in the <update>
parameter.
For example, given a books
collection with the following document:
The following operation uses:
- the
$inc
operator to increment thestock
field; and - the
$set
operator to replace the value of theitem
field, thepublisher
field in theinfo
embedded document, thetags
field, and the second element in theratings
array.
The updated document is the following:
See also
Replace All Fields¶
Given the following document in the books
collection:
The following operation passes an <update>
document that contains
only field and value pairs. The <update>
document completely
replaces the original document except for the _id
field.
The updated document contains only the fields from the replacement
document and the _id
field. That is, the fields ratings
and
reorder
no longer exist in the updated document since the fields
were not in the replacement document.
Insert a New Document if No Match Exists¶
The following update sets the upsert option
to true
so that update()
creates a new
document in the books
collection if no document matches the
<query>
parameter:
If no document matches the <query>
parameter, the update operation
inserts a document with only the fields and values of the
<update>
document and a new unique ObjectId
for the _id
field:
For more information on upsert
option and the inserted document,
Upsert Option.
Update Multiple Documents¶
To update multiple documents, set the multi
option to true
. For
example, the following operation updates all documents where stock
is less than or equal to 10
:
If the reorder
field does not exist in the matching document(s),
the $set
operator will add the field with the specified
value. See $set
for more information.
Override Default Write Concern¶
The following operation on a replica set specifies a write
concern of "w: majority"
with a
wtimeout
of 5000 milliseconds such that the method returns after
the write propagates to a majority of the replica set members or the
method times out after 5 seconds.
Combine the upsert
and multi
Options¶
Given a books
collection that includes the following documents:
The following operation specifies both the multi
option and the
upsert
option. If matching documents exist, the operation updates
all matching documents. If no matching documents exist, the operation
inserts a new document.
The operation updates all matching documents and results in the following:
If the collection had no matching document, the operation would
result in the insertion of a document using the fields from both the
<query>
and the <update>
specifications:
For more information on upsert
option and the inserted document,
Upsert Option.
WriteResult¶
Changed in version 2.6.
Successful Results¶
The 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 update()
method encounters write
concern errors, the results include the
WriteResult.writeConcernError
field:
See also