- MongoDB CRUD Operations >
- Update Documents
Update Documents¶
On this page
Update¶
MongoDB provides the following methods for updating documents in a collection:
db.collection.updateOne() |
Updates at most a single document that match a specified filter even though multiple documents may match the specified filter. New in version 3.2. |
db.collection.updateMany() |
Update all documents that match a specified filter. New in version 3.2. |
db.collection.replaceOne() |
Replaces at most a single document that match a specified filter even though multiple documents may match the specified filter. New in version 3.2. |
db.collection.update() |
Either updates or replaces a single document that match a specified filter or updates all documents that match a specified filter. By default, the |
These methods accept as parameters:
a filter document to determine which documents to update. These filters use the same syntax as read operations:
A query filter document can specify equality condition with
<field>:<value>
expressions to select all documents that contain the<field>
with the specified<value>
:A query filter document can use the query operators to specify conditions in the following form:
an update document to specify the modification to perform or a replacement document that wholly replaces the matching documents except for the
_id
field, andan options document.
Behavior¶
Atomicity¶
All write operations in MongoDB are atomic on the level of a single document. For more information on MongoDB and atomicity, see Atomicity and Transactions.
_id
Field¶
Once set, you cannot update the value of the _id
field nor can you
replace an existing document with a replacement document that has a
different _id
field value.
Document Size¶
For MMAPv1, when performing update operations that increase the document size beyond the allocated space for that document, the update operation relocates the document on disk.
Field Order¶
MongoDB preserves the order of the document fields following write operations except for the following cases:
- The
_id
field is always the first field in the document. - Updates that include
renaming
of field names may result in the reordering of fields in the document.
Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the field order in a document. Before version 2.6, MongoDB did not actively preserve the order of the fields in a document.
Upsert
Option¶
If db.collection.update()
,
db.collection.updateOne()
,
db.collection.updateMany()
, or
db.collection.replaceOne()
includes upsert : true
and
no documents match the specified filter, then the operation creates a
new document and inserts it. If there are matching documents, then the
operation modifies or replaces the matching document or documents.
For details on the new document created, see the individual reference pages for the methods.
Example Collection¶
The examples on this page use the db.collection.find()
method
in the mongo
shell. In the mongo
shell, if the returned cursor is not assigned to a variable using the
var
keyword, then the cursor is automatically iterated up to 20
times [1] to print up to the first 20 documents in
the results.
To populate the users
collection referenced in the examples,
run the following in mongo
shell:
Note
If the users
collection already contains documents with the same
_id
values, you need to drop
the collection (db.users.drop()
) before inserting the example
documents.
Update Specific Fields in a Document¶
To change a field in a document, MongoDB provides update
operators, such as $set
to
modify values.
To specify the modification to perform using update operators, use an update document of the form:
Some update operators, such as $set
, will create the field if
the field does not exist. See the individual update operator reference.
db.collection.updateOne()
¶
New in version 3.2.
The following example uses the db.collection.updateOne()
method on the users
collection to update the first document that
matches the filter favorites.artist
equals "Picasso"
. The update
operation:
- uses the
$set
operator to update the value of thefavorites.food
field to"pie"
and the value of thetype
field to3
, - uses the
$currentDate
operator to update the value of thelastModified
field to the current date. IflastModified
field does not exist,$currentDate
will create the field. See$currentDate
for details.
For more information and examples, see
db.collection.updateOne()
.
db.collection.updateMany()
¶
New in version 3.2.
The following example uses the db.collection.updateMany()
method on the users
collection to update all documents that matches
the filter favorites.artist
equals "Picasso"
. The update operation:
- uses the
$set
operator to update the value of thefavorites.artist
field to"Pisanello"
and the value of thetype
field to3
, - uses the
$currentDate
operator to update the value of thelastModified
field to the current date. IflastModified
field does not exist,$currentDate
will create the field. See$currentDate
for details.
For more information and examples, see
db.collection.updateMany()
.
db.collection.update
¶
The following example uses the db.collection.update()
method
on the users
collection to update the first document that matches
the filter favorites.artist
equals "Pisanello"
. The update operation:
- uses the
$set
operator to update the value of thefavorites.food
field to"pizza"
and the value of thetype
field to0
, - uses the
$currentDate
operator to update the value of thelastModified
field to the current date. IflastModified
field does not exist,$currentDate
will create the field. See$currentDate
for details.
To update multiple documents using the
db.collection.update()
, include the multi: true option:
Replace the Document¶
To replace the entire content of a document except for the _id
field, pass an entirely new document as the second argument to
db.collection.replaceOne()
or
db.collection.update()
. When replacing a document, the
replacement document must consist of only <field> : <value>
.
The replacement document can have different fields from the original
document. In the replacement document, you can omit the _id
field
since the _id
field is immutable; however, if you do include the
_id
field, it must have the same value as the current value.
db.collection.replaceOne
¶
The following example uses the db.collection.replaceOne()
method on the users
collection to replace the first document that
matches the filter name
equals "abc"
with the new document:
db.collection.update
¶
The following example uses the db.collection.update()
method on the users
collection to replace the first document that
matches the filter name
equals "xyz"
with the new document:
Additional Methods¶
The following methods can also update documents from a collection:
db.collection.findOneAndReplace()
.db.collection.findOneAndUpdate()
.db.collection.findAndModify()
.db.collection.save()
.db.collection.bulkWrite()
.
See the individual reference pages for the methods for more information and examples.
Write Acknowledgement¶
With write concerns, you can specify the level of acknowledgement requested from MongoDB for write operations. For details, see Write Concern.
[1] | You can use the DBQuery.shellBatchSize to
change the number of iteration from the default value 20 . See
Working with the mongo Shell for more information. |