Bulk.execute()

Tip

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

Description

• Bulk.execute()

New in version 2.6.

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

Bulk.execute() accepts the following parameter:

ParameterTypeDescriptionwriteConcerndocumentOptional. Write concern document for the bulkoperation as a whole. Omit to use default. For a standalonemongod server, the write concern defaults to { w: 1 }.With a replica set, the default write concern is { w: 1 } unlessmodified 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 ina transaction. To use write concern with transactions, seeTransactions and Write Concern.

Returns:A BulkWriteResult object that contains thestatus of the operation.

After execution, you cannot re-execute the Bulk()object without reinitializing. Seedb.collection.initializeUnorderedBulkOp() anddb.collection.initializeOrderedBulkOp().

Behavior

Ordered Operations

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

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.

Examples

Execute Bulk Operations

The following initializes a Bulk() operations builder on theitems collection, adds a series of insert operations, and executesthe 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(). Fordetails on the batches executed, see Bulk.getOperations().

Override Default Write Concern

The following operation to a replica set specifies a writeconcern of "w: majority" with awtimeout of 5000 milliseconds such that the method returns afterthe writes propagate to a majority of the voting replica set members orthe method times out after 5 seconds.

Changed in version 3.0: In previous versions, majority referred to the majority of allmembers of the replica set instead of the majority of the votingmembers.

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" : [ ]
})

See

Bulk() for a listing of methods available for bulkoperations.