- Core MongoDB Operations (CRUD) >
- Update
Update¶
Of the four basic database operations (i.e. CRUD), update operations are those that modify existing records or documents in a MongoDB collection. For general information about write operations and the factors that affect their performance, see Write Operations; for documentation of other CRUD operations, see the Core MongoDB Operations (CRUD) page.
Overview¶
Update operation modifies an existing document or documents in a collection. MongoDB provides the following methods to perform update operations:
Note
Consider the following behaviors of MongoDB’s update operations.
When performing update operations that increase the document size beyond the allocated space for that document, the update operation relocates the document on disk and may reorder the document fields depending on the type of update.
As of these driver versions, all write operations will issue a
getLastError
command to confirm the result of the write operation:Refer to the documentation on write concern in the Write Operations document for more information.
Update¶
The update()
method is the primary method used
to modify documents in a MongoDB collection. By default, the
update()
method updates a single document,
but by using the multi
option, update()
can update all documents that match the query criteria in the
collection. The update()
method can either
replace the existing document with the new document or update specific
fields in the existing document.
The update()
has the following syntax
[1]:
Corresponding operation in SQL
The update()
method corresponds to the
UPDATE
operation in SQL, and:
- the
<query>
argument corresponds to theWHERE
statement, and - the
<update>
corresponds to theSET ...
statement.
The default behavior of the update()
method
updates a single document and would correspond to the SQL
UPDATE
statement with the LIMIT 1
. With the multi
option, update()
method would correspond to
the SQL UPDATE
statement without the LIMIT
clause.
[1] | This examples uses the interface added in
MongoDB 2.2 to specify the Prior to version 2.2, in the |
Modify with Update Operators¶
If the <update>
argument contains only update operator expressions such as the $set
operator expression, the update()
method updates the corresponding fields in the document. To update
fields in subdocuments, MongoDB uses dot notation.
Update a Field in a Document¶
Use $set
to update a value of a field.
The following operation queries the bios
collection for the first
document that has an _id
field equal to 1
and sets the value of
the field middle
, in the subdocument name
, to Warner
:
Add a New Field to a Document¶
If the <update>
argument contains fields not currently in the
document, the update()
method adds
the new fields to the document.
The following operation queries the bios
collection for the first
document that has an _id
field equal to 3
and adds to that
document a new mbranch
field and a new aka
field in the
subdocument name
:
Remove a Field from a Document¶
If the <update>
argument contains $unset
operator, the
update()
method removes the field
from the document.
The following operation queries the bios
collection for the first
document that has an _id
field equal to 3
and removes the
birth
field from the document:
Update Arrays¶
Update an Element by Specifying Its 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 without Specifying Its Position¶
The update()
method can perform the
update using the $
positional operator if the position is
not known. The array field must appear in the query
argument 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 without Specifying Its Position¶
The update()
method can perform the
update of an array that contains subdocuments by using the positional
operator (i.e. $
) and the dot notation.
The following operation queries the bios
collection for the first
document where the _id
field equals 6
and the awards
array
contains a subdocument element with the by
field equal to ACM
.
If found, the update()
method
updates the by
field in the first matching subdocument:
Add an Element to an Array¶
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:
Update Multiple Documents¶
If the <options>
argument contains the multi
option set to
true
or 1
, the update()
method updates
all documents that match the query.
The following operation queries the bios
collection for all
documents where the awards
field contains a subdocument element
with the award
field equal to Turing
and sets the turing
field to true
in the matching documents [2]:
[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. |
Replace Existing Document with New Document¶
If the <update>
argument contains only field and value pairs, the
update()
method replaces the
existing document with the document in the <update>
argument,
except for the _id
field.
The following operation queries the bios
collection for the first
document that has a name
field equal to { first: 'John', last:
'McCarthy' }
and replaces all but the _id
field in the document
with the fields in the <update>
argument:
update()
Operations with the upsert
Flag¶
If you set the upsert
option in the <options>
argument to
true
or 1
and no existing document match the <query>
argument, the update()
method can
insert a new document into the collection. [3]
The following operation queries the bios
collection for a document
with the _id
field equal to 11
and the name
field equal to
{ first: 'James', last: 'Gosling'}
. If the query selects a
document, the operation performs an update operation. If a document is
not found, update()
inserts a new
document containing the fields and values from <query>
argument
with the operations from the <update>
argument applied.
[4]
See also Update Operations with the Upsert Flag in the Create 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. |
[4] | If the <update> argument includes
only field and value pairs, the new document contains the fields and
values specified in the <update> argument. If the <update>
argument includes only update operators, the new document contains the fields and
values from <query> argument with the operations from the
<update> argument applied. |
Save¶
The save()
method performs a special type of
update()
, depending on the _id
field of
the specified document.
The save()
method has the
following syntax:
Behavior¶
If you specify a document with an _id
field,
save()
performs an
update()
with the upsert
option set: if
an existing document in the collection has the same _id
,
save()
updates that document, and inserts the
document otherwise. If you do not specify a document with an _id
field to save()
, performs an
insert()
operation.
That is, save()
method is equivalent to the
update()
method with the upsert
option
and a <query>
argument with an _id
field.
Example
Consider the following psudocode explanation of
save()
as an illustration of its
behavior:
Save Performs an Update¶
If the <document>
argument contains the _id
field that exists
in the collection, the save()
method
performs an update that replaces the existing document with the
<document>
argument.
The following operation queries the bios
collection for a document
where the _id
equals ObjectId("507c4e138fada716c89d0014")
and
replaces the document with the <document>
argument:
See also
Insert a Document with save() and Update operations with save() in the Create section.