Bulk.execute()

On this page

Description

Behavior
Examples

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

Tip

Starting in version 3.2, MongoDB also provides the db.collection.bulkWrite() method for performing bulk write operations.

Description

Bulk.execute()

Executes the list of operations built by the Bulk() operations builder.

Bulk.execute() accepts the following parameter:

Parameter	Type	Description
`writeConcern`	document	Optional. Write concern document for the bulk operation as a whole. Omit to use default. For a standalone `mongod` server, the write concern defaults to `{ w: 1 }`. With a replica set, the default write concern is `{ w: 1 }` unless modified as part of the replica set configuration. See Override Default Write Concern for an example. Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.

Returns:	A `BulkWriteResult()` object that contains the status of the operation.

After execution, you cannot re-execute the Bulk() object without reinitializing. See db.collection.initializeUnorderedBulkOp() and db.collection.initializeOrderedBulkOp().

Behavior

Ordered Operations

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.

Bulk() operations and comparable methods in the drivers do not have a limit for the number of operations in a group. To see how the operations are grouped for bulk operation execution, call Bulk.getOperations() after the execution.

Tip

Unordered Operations

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.

Tip

Transactions

Bulk() can be used inside distributed transactions.

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

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

Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.

Important

In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for distributed transactions.

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

Examples

Execute Bulk Operations

The following initializes a Bulk() operations builder on the items collection, adds a series of insert operations, and executes the operations:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } );
bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } );
bulk.execute( );

The operation returns the following BulkWriteResult() object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 2,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

For details on the return object, see BulkWriteResult(). For details on the batches executed, see Bulk.getOperations().

Override Default Write Concern

The following operation to a replica set specifies a write concern of "w: majority" with a wtimeout of 5000 milliseconds such that the method returns after the writes propagate to a majority of the voting replica set members or the method times out after 5 seconds.

var bulk = db.items.initializeUnorderedBulkOp();
bulk.insert( { item: "efg123", status: "A", defaultQty: 100, points: 0 } );
bulk.insert( { item: "xyz123", status: "A", defaultQty: 100, points: 0 } );
bulk.execute( { w: "majority", wtimeout: 5000 } );

The operation returns the following BulkWriteResult() object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 2,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

Tip

See:

Bulk() for a listing of methods available for bulk operations.

Back

Bulk()

Bulk.find()