Bulk()

Tip

Starting in version 3.2, MongoDB also provides thedb.collection.bulkWrite() method for performing bulkwrite operations.

Description

• Bulk()

New in version 2.6.

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

Ordered and Unordered Bulk Operations

The builder can construct the list of operations as ordered orunordered.

Ordered Operations

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

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

When executing an ordered list of operations, MongoDBgroups the operations by the operation type andcontiguity; i.e. contiguous operations of the same type are groupedtogether. For example, if an ordered list has two insert operationsfollowed by an update operation followed by another insert operation,MongoDB groups the operations into three separate groups: first groupcontains the two insert operations, second group contains the updateoperation, and the third group contains the last insert operation. Thisbehavior 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 intosmaller groups of 1000 or less. For example, if the bulk operations listconsists of 2000 insert operations, MongoDB creates 2 groups, each with1000 operations.

The sizes and grouping mechanics are internal performance details andare 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 asharded collection will generally be slower than executing anunordered listsince with an ordered list, each operation must wait for the previousoperation 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 thelist. If an error occurs during the processing of one of the writeoperations, MongoDB will continue to process remaining write operationsin the list.

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

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

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

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

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

Transactions

Bulk() can be used inside multi-document transactions.

For Bulk.find.insert() operations, the collection must already exist.

For Bulk.find.upsert(), if the operation results in anupsert, the collection must already exist.

Do not explicitly set the write concern for the operation if run ina transaction. To use write concern with transactions, seeTransactions and Write Concern.

Important

In most cases, multi-document transaction incurs a greaterperformance cost over single document writes, and theavailability of multi-document transactions should not be areplacement for effective schema design. For many scenarios, thedenormalized data model (embedded documents and arrays) will continue to be optimal for yourdata and use cases. That is, for many scenarios, modeling your dataappropriately will minimize the need for multi-documenttransactions.

For additional transactions usage considerations(such as runtime limit and oplog size limit), see alsoProduction Considerations.

Methods

The Bulk() builder has the following methods: