- 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 existing document or documents or replace an existing document entirely, depending on the update parameter.
By default, the
update()
method updates a single document. If themulti
option is set totrue
, the method updates all documents that match the query criteria.Changed in version 2.2: Added the following overloaded
update()
function:Prior to version 2.2, the
update()
method has the following form: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. The syntax for this parameter depends on the MongoDB version. See Upsert Parameter.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.To update fields in embedded documents, use dot notation.
The
update()
method can modify the name of afield
using the$rename
operator.
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 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. For an example, see Update Specific Fields.
Replace a Document Entirely¶
If the <update>
document contains only field:value
expressions, and no modifiers, 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 Parameter¶
In MongoDB versions 2.2 and later, the upsert parameter has the following form:
Prior to version 2.2, the upsert parameter is a positional Boolean.
To enable, specify true
as the third parameter to
update()
.
Upsert Behavior¶
If upsert is set to true
, and if 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, or - The fields and values of the both the
<query>
and<update>
parameters. The update creates a document with data from both<query>
and<update>
if the<update>
parameter contains only update operator expressions by taking any equality clauses from the<query>
as the base document.
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 operation at the same time. The
following operation becomes an insert
because the upsert
flag is true
.:
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 perform 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 an applications issues a group of upsert
operations, 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¶
In MongoDB versions 2.2 and later, the multi
parameter has the
following form:
Prior to version 2.2, the multi
parameter is a positional Boolean.
To enable the multiple updates, specify true
as the fourth parameter
to update()
.
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.
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 $set
and $inc
operators to add a price
field and to increment stock
by 5
.
The updated document is now the following:
Update Specific Fields in Embedded Documents¶
Use dot notation to update values in embedded documents.
The following example, which uses the bios collection, queries for the document with
_id
equal to 1
and updates the value of the field middle
in
the embedded document named name
:
Add New Fields¶
If the <update>
parameter contains fields not currently in the
document, the update()
method adds the new
fields to the document. The following operation adds two new fields:
mbranch
and aka
. The operation adds aka
in the
name
document:
Remove Fields¶
The following operation uses the $unset
operator to remove
the birth
field from the document that has _id
equal to 3
:
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, which means the document replaces all the
fields in the original document. The operation does not replace the
_id
value. The operation contains the same value for the item
field in both the <query>
and <update>
documents, which means
the field does not change:
The operation creates the following new document. The operation removed
the author
field and changed the values of the price
and
stock
fields:
In the next example, which uses the bios collection, the operation changes all values
for the document including the value used to locate the document. The
operation locates a document by querying for name
set to { first:
"John", last: "McCarthy" }
and then issues a replacement document that
includes the name
field set to { first: "Ken", last: "Iverson"
}
.
Insert a New Document if No Match Exists (Upsert)¶
The following command sets the upsert option to true
[1] 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 upsert inserts
a document with the fields and values of the <update>
parameter and
a new unique ObjectId
for the _id
field:
In the next example, the <update>
parameter includes only
update operators. If no document matches the
<query>
parameter, the update operation inserts a document with the fields
and values of the both the <query>
and <update>
parameters:
[1] | Prior to version 2.2, in the mongo shell, you would specify
the upsert and the multi options in the
update() method as positional boolean options.
See update() for details. |
Update Multiple Documents¶
To update multiple documents, set the multi
option to true
[2]. The following example queries the
bios collection for all
documents where awards.award
is set to Turing
. The update sets
the turing
field to true
:
[2] | Prior to version 2.2, in the mongo shell, you would specify
the upsert and the multi options in the
update() method as positional boolean options.
See update() for details. |
Combine the Upsert and Multi Parameters¶
Given a books
collection that includes the following documents:
The following command specifies the multi
parameter to update all
documents where item
is "Divine Comedy"
and the author
is
"Dante"
and specifies the upsert
parameter to create a new
document if no matching documents are found
[3]:
The operation updates all three matching documents and results in the following:
If the collection had no matching document, the operation would result in the insertion of a document:
[3] | Prior to version 2.2, in the mongo shell, you would specify
the upsert and the multi options in the
update() method as positional boolean options.
See update() for details. |
Update Arrays¶
Update an Element by Position¶
If the update operation requires an update of an element in an array
field, the update()
method can
perform the update using the position of the element and dot
notation. Arrays in MongoDB are zero-based.
The following operation queries the bios collection for the first document with
_id
field equal to 1
and updates the second element in the
contribs
array:
Update an Element if Position is Unknown¶
If the position in the array is not known, the
update()
method can perform the update using
the $
positional operator. The array field must appear in
the <query>
parameter in order to determine which array element to
update.
The following operation queries the bios collection for the first document where the
_id
field equals 3
and the contribs
array contains an
element equal to compiler
. If found, the
update()
method updates the first matching
element in the array to A compiler
in the document:
Update a Document Element¶
The update()
method can perform the
update of an array that contains embedded documents by using the positional
operator (i.e. $
) and dot notation.
The following example queries the bios collection for the first document where the
_id
field equals 6
and the awards
array contains an embedded
document where the by
field equals ACM
. If found, the
update()
method updates the by
field in
the first matching embedded document:
Add an Element¶
The following operation queries the bios collection for the first document that has an
_id
field equal to 1
and adds a new element to the awards
field:
In the next example, the $set
operator uses dot
notation to access the middle
field in the
name
embedded document. The $push
operator adds another document to the awards
array.
Consider the following operation:
This update()
operation:
- Modifies the field
name
whose value is an embedded document. Specifically, the$set
operator updates themiddle
field in thename
document. The document uses dot notation to access a field in an embedded document. - Adds an element to the field
awards
, whose value is an array. Specifically, the$push
operator adds another document as element to the fieldawards
.