Docs4dev
Docs
mongodb / v3.6 / reference / reference-method-db.collection.bulkWrite.html

db.collection.bulkWrite()

On this page

Definition

db.collection. bulkWrite ( )

New in version 3.2.

Performs multiple write operations with controls for order of execution.

bulkWrite() has the following syntax:

db.collection.bulkWrite(
   [ <operation 1>, <operation 2>, ... ],
   {
      writeConcern : <document>,
      ordered : <boolean>
   }
)
Parameter Type Description
operations array

An array of bulkWrite() write operations.

Valid operations are:

See Write Operations for usage of each operation.
writeConcern document Optional. A document expressing the write concern. Omit to use the default write concern.
ordered boolean

Optional. A boolean specifying whether the mongod instance should perform an ordered or unordered operation execution. Defaults to true.

See Execution of Operations
Returns:
  • A boolean acknowledged as true if the operation ran with write concern or false if write concern was disabled.
  • A count for each write operation.
  • An array containing an _id for each successfully inserted or upserted documents.

Behavior

bulkWrite() takes an array of write operations and executes each of them. By default operations are executed in order. See Execution of Operations for controlling the order of write operation execution.

Write Operations

insertOne

Inserts a single document into the collection.

See db.collection.insertOne().

db.collection.bulkWrite( [
   { insertOne : { "document" : <document> } }
] )

updateOne and updateMany

Changed in version 3.6: The updateOne and updateMany operations add support for arrayFilters parameter that determines which elements to modify in an array field. Refer to db.collection.updateOne() and db.collection.updateMany() for details.

Changed in version 3.4: Add support for collation. Refer to db.collection.updateOne() and db.collection.updateMany() for details

updateOne updates a single document in the collection that matches the filter. If multiple documents match, updateOne will update the first matching document only. See db.collection.updateOne().

db.collection.bulkWrite( [
   { updateOne :
      {
         "filter" : <document>,
         "update" : <document>,
         "upsert" : <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ]
      }
   }
] )

updateMany updates all documents in the collection that match the filter. See db.collection.updateMany().

db.collection.bulkWrite( [
   { updateMany :
      {
         "filter" : <document>,
         "update" : <document>,
         "upsert" : <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ]
      }
   }
] )

Use query selectors such as those used with find() for the filter field.

Use Update Operators such as $set, $unset, or $rename for the update field.

By default, upsert is false.

replaceOne

Changed in version 3.4: Add support for collation. Refer to db.collection.replaceOne() for details

replaceOne replaces a single document in the collection that matches the filter. If multiple documents match, replaceOne will replace the first matching document only. See db.collection.replaceOne().

db.collection.bulkWrite([
   { replaceOne :
      {
         "filter" : <document>,
         "replacement" : <document>,
         "upsert" : <boolean>
      }
   }
] )

Use query selectors such as those used with find() for the filter field.

The replacement field cannot contain update operators.

By default, upsert is false.

deleteOne and deleteMany

Changed in version 3.4: Add support for collation. Refer to db.collection.deleteOne() and db.collection.deleteMany() for details

deleteOne deletes a single document in the collection that match the filter. If multiple documents match, deleteOne will delete the first matching document only. See db.collection.deleteOne().

db.collection.bulkWrite([
   { deleteOne :  { "filter" : <document> } }
] )

deleteMany deletes all documents in the collection that match the filter. See db.collection.deleteMany().

db.collection.bulkWrite([
   { deleteMany :  { "filter" : <document> } }
] )

Use query selectors such as those used with find() for the filter field.

_id Field

If the document does not specify an _id field, then mongod adds the _id field and assign a unique ObjectId for the document before inserting or upserting it. Most drivers create an ObjectId and insert the _id field, but the mongod will create and populate the _id if the driver or application does not.

If the document contains an _id field, the _id value must be unique within the collection to avoid duplicate key error.

Update or replace operations cannot specify an _id value that differs from the original document.

Execution of Operations

The ordered parameter specifies whether bulkWrite() will execute operations in order or not. By default, operations are executed in order.

The following code represents a bulkWrite() with five operations.

db.collection.bulkWrite(
   [
      { insertOne : <document> },
      { updateOne : <document> },
      { updateMany : <document> },
      { replaceOne : <document> },
      { deleteOne : <document> },
      { deleteMany : <document> }
   ]
)

In the default ordered : true state, each operation will be executed in order, from the first operation insertOne to the last operation deleteMany.

If ordered is set to false, operations may be reordered by mongod to increase performance. Applications should not depend on order of operation execution.

The following code represents an unordered bulkWrite() with six operations:

db.collection.bulkWrite(
   [
      { insertOne : <document> },
      { updateOne : <document> },
      { updateMany : <document> },
      { replaceOne : <document> },
      { deleteOne : <document> },
      { deleteMany : <document>