OPTIONS

Bulk()

Description

Bulk()

New in version 2.6.

Bulk operations builder used to construct a list of write operations to perform in bulk for a single collection. To instantiate the builder, use either the db.collection.initializeOrderedBulkOp() or the db.collection.initializeUnorderedBulkOp() method.

Ordered and Unordered Bulk Operations

The builder can construct the list of operations as ordered or unordered.

Ordered Operations

With an ordered operations list, MongoDB executes the write operations in the list serially. If an error occurs during the processing of one of the write operations, MongoDB will return without processing any remaining write operations in the list.

Use db.collection.initializeOrderedBulkOp() to create a builder for an ordered list of write commands.

When executing an ordered list of operations, MongoDB groups the operations by the operation type and contiguity; i.e. contiguous operations of the same type are grouped together. For example, if an ordered list has two insert operations followed by an update operation followed by another insert operation, MongoDB groups the operations into three separate groups: first group contains the two insert operations, second group contains the update operation, and the third group contains the last insert operation. This behavior is subject to change in future versions.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Executing an ordered list of operations on a sharded collection will generally be slower than executing an unordered list since with an ordered list, each operation must wait for the previous operation to finish.

Unordered Operations

With an unordered operations list, MongoDB can execute in parallel, as well as in a nondeterministic order, the write operations in the list. If an error occurs during the processing of one of the write operations, MongoDB will continue to process remaining write operations in the list.

Use db.collection.initializeUnorderedBulkOp() to create a builder for an unordered list of write commands.

When executing an unordered list of operations, MongoDB groups the operations. With an unordered bulk operation, the operations in the list may be reordered to increase performance. As such, applications should not depend on the ordering when performing unordered bulk operations.

Each group of operations can have at most 1000 operations. If a group exceeds this limit, MongoDB will divide the group into smaller groups of 1000 or less. For example, if the bulk operations list consists of 2000 insert operations, MongoDB creates 2 groups, each with 1000 operations.

The sizes and grouping mechanics are internal performance details and are subject to change in future versions.

To see how the operations are grouped for a bulk operation execution, call Bulk.getOperations() after the execution.

Methods

The Bulk() builder has the following methods:

Name Description
Bulk.insert() Adds an insert operation to a list of operations.
Bulk.find() Specifies the query condition for an update or a remove operation.
Bulk.find.removeOne() Adds a single document remove operation to a list of operations.
Bulk.find.remove() Adds a multiple document remove operation to a list of operations.
Bulk.find.replaceOne() Adds a single document replacement operation to a list of operations.
Bulk.find.updateOne() Adds a single document update operation to a list of operations.
Bulk.find.update() Adds a multi update operation to a list of operations.
Bulk.find.upsert() Specifies the upsert flag for an update operation.
Bulk.execute() Executes a list of operations in bulk.
Bulk.getOperations() Returns an array of write operations executed in the Bulk() operations object.
Bulk.tojson() Returns a JSON document that contains the number of operations and batches in the Bulk() operations object.
Bulk.toString() Returns the Bulk.tojson() results as a string.