OPTIONS

Write Operations Overview

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 components of a MongoDB insert operations.

The components of a MongoDB insert operations.

The following diagram shows the same query in SQL:

The components of a SQL INSERT statement.

The components of a SQL INSERT statement.

Example

The following operation inserts a new documents 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.

db.users.insert(
   {
      name: "sue",
      age: 26,
      status: "A"
   }
)

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 components of a MongoDB update operation.

The components of a MongoDB update operation.

The following diagram shows the same query in SQL:

The components of a SQL UPDATE statement.

The components of a SQL UPDATE statement.

Example

db.users.update(
   { age: { $gt: 18 } },
   { $set: { status: "A" } },
   { multi: true }
)

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.

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 components of a MongoDB remove operation.

The components of a MongoDB remove operation.

The following diagram shows the same query in SQL:

The components of a SQL DELETE statement.

The components of a SQL DELETE statement.

Example

db.users.remove(
   { status: "D" }
)

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 sub-documents within that document. For write operations that modify multiple documents, the operation as a whole is not atomic, and other operations may interleave.

No other operations are atomic. You can, however, attempt to isolate a write operation that affects multiple documents using the isolation operator.

To isolate a sequence of write operations from other read and write operations, see Perform Two Phase Commits.

Additional Methods

The db.collection.save() method can either update an existing document or an 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.