- MongoDB CRUD Operations >
- MongoDB CRUD Concepts >
- Write Operations >
- Write Operations Overview
Write Operations Overview¶
On this page
A write operation is any operation that creates or modifies data in the MongoDB instance. In MongoDB, write operations target a single collection. All write operations in MongoDB are atomic on the level of a single document.
There are three classes of write operations in MongoDB: insert, update, and remove. Insert operations add new data to a collection. Update operations modify existing data, and remove operations delete data from a collection. No insert, update, or remove can affect more than one document atomically.
For the update and remove operations, you can specify criteria, or conditions, that identify the documents to update or remove. These operations use the same query syntax to specify the criteria as read operations.
MongoDB allows applications to determine the acceptable level of acknowledgement required of write operations. See Write Concern for more information.
Insert¶
In MongoDB, the db.collection.insert()
method adds new
documents to a collection.
The following diagram highlights the components of a MongoDB insert operation:
The following diagram shows the same query in SQL:
Example
The following operation inserts a new document into the users
collection. The new document has four fields name
, age
, and
status
, and an _id
field. MongoDB always adds the _id
field to the new document if that field does not exist.
For more information and examples, see db.collection.insert()
.
Insert Behavior¶
If you add a new document without the _id field, the client
library or the mongod
instance adds an _id
field and
populates the field with a unique ObjectId.
If you specify the _id
field, the value must be unique within the
collection. For operations with write concern,
if you try to create a document with a duplicate _id
value,
mongod
returns a duplicate key exception.
Other Methods to Add Documents¶
You can also add new documents to a collection using methods that have
an upsert option. If the option
is set to true
, these methods will either modify existing documents
or add a new document when no matching documents exist for the query.
For more information, see Update Behavior with the upsert Option.
Update¶
In MongoDB, the db.collection.update()
method modifies
existing documents in a collection. The
db.collection.update()
method can accept query criteria to
determine which documents to update as well as an options document that
affects its behavior, such as the multi
option to update multiple
documents.
Operations performed by an update are atomic within a single document. For
example, you can safely use the $inc
and $mul
operators to
modify frequently-changed fields in concurrent applications.
The following diagram highlights the components of a MongoDB update operation:
The following diagram shows the same query in SQL:
Example
This update operation on the users
collection sets the
status
field to A
for the documents that match the criteria
of age
greater than 18
.
For more information, see db.collection.update()
and
update() Examples.
Default Update Behavior¶
By default, the db.collection.update()
method updates a
single document. However, with the multi
option,
update()
can update all documents in a
collection that match a query.
The db.collection.update()
method either updates specific
fields in the existing document or replaces the document. See
db.collection.update()
for details as well as examples.
When performing update operations that increase the document size beyond the allocated space for that document, the update operation relocates the document on disk.
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.
Update Behavior with the upsert
Option¶
If the update()
method includes upsert:
true and no documents match the query portion of
the update operation, then the update operation creates a new document.
If there are matching documents, then the update operation with the
upsert: true modifies the matching document
or documents.
By specifying upsert: true, applications can indicate,
in a single operation, that if no matching documents are found for
the update, an insert should be performed. See
update()
for details on performing an
upsert.
Changed in version 2.6: In 2.6, the new Bulk()
methods and the underlying
update
command allow you to perform many updates with
upsert: true
operations in a single call.
If you create documents using the upsert
option to
update()
consider using a a unique index to prevent duplicated operations.
Remove¶
In MongoDB, the db.collection.remove()
method deletes
documents from a collection. The db.collection.remove()
method accepts a query criteria to determine which documents to remove.
The following diagram highlights the components of a MongoDB remove operation:
The following diagram shows the same query in SQL:
Example
This delete operation on the users
collection removes all
documents that match the criteria of status
equal to D
.
For more information, see db.collection.remove()
method and
Remove Documents.
Remove Behavior¶
By default, db.collection.remove()
method removes all
documents that match its query. However, the method can accept a flag
to limit the delete operation to a single document.
Isolation of Write Operations¶
The modification of a single document is always atomic, even if the write operation modifies multiple embedded documents within that document. No other operations are atomic.
If a write operation modifies multiple documents, the operation as a whole is not atomic, and other operations may interleave. You can, however, attempt to isolate a write operation that affects multiple documents using the isolation operator.
For more information Atomicity and Transactions.
Additional Methods¶
The db.collection.save()
method can either update an existing
document or insert a document if the document cannot be found by the
_id
field. See db.collection.save()
for more information
and examples.
MongoDB also provides methods to perform write operations in bulk. See
Bulk()
for more information.