Database Manual / Reference / mongosh Methods / Bulk Operations

Mongo.bulkWrite() (mongosh method)

Definition

Mongo.bulkWrite(operations, options)

bulkWrite() performs multiple write operations across multiple databases and collections in a single call. This method replaces db.collection.bulkWrite(), which performs multiple write operations to a specific collection in a single call.

Note

You can only use Mongo.bulkWrite() with MongoDB 8.0 or later.

Syntax

You can call bulkWrite() on the current Mongo() instance by using the following syntax:

db.getMongo().bulkWrite(
  [
    {
      namespace: "<db1.collection1>",
      name: "insertOne",
      document: { ... }
    },
    {
      namespace: "<db2.collection2>",
      name: "replaceOne",
      filter: { ... }
    }
  ],
  {
    ordered: boolean,
    verboseResults: boolean,
    bypassDocumentValidation: boolean,
    let: Document
  }
)

You can also call it on a different Mongo instance, like in the following example:

const otherMongo = Mongo("<other connection string>");

otherMongo.bulkWrite([{ namespace: "<db.collection>", ... }]);

bulkWrite() accepts two parameters:

Parameter	Type	Description
`operations`	Array of documents	Defines an array of write operations. Each document in the array represents a write operation that you want to execute.
`options`	Document	Defines options for the operation.

A document in operations can represent one of six operations:

insert one
replace one
update one
update many
delete one
delete many

The following sections describe the syntax you must use for documents that represent each operation.

Insert One

{
   namespace: '<db.collection>',
   name: 'insertOne',
   document: Document
}

Field	Type	Description
`namespace`	String	The database and collection that you want to insert the document into.
`name`	String	The operation. Set to `"insertOne"` for an insert one operation.
`document`	Document	The document that you want to insert.

Note

If you do not specify an _id field in the document to insert, mongosh automatically generates an _id.

Update One or Many

{
   namespace: '<db>.<collection>',
   name: 'updateOne' | 'updateMany',
   filter: Document,
   update: Document | Document[],
   arrayFilters?: Document[],
   hint?: Document | string,
   collation?: Document,
   upsert?: boolean
}

Field	Type	Description
`namespace`	String	The database and collection that you want to update documents in.
`name`	String	The operation. Set to `"updateOne"` for an update one operation. Set to `"updateMany"` for an update many operation.
`filter`	Document	The filter that matches one or more documents you want to update. During an update one operation, `mongosh` only updates the first matching document. During an update many operation, `mongosh` updates all documents that match the filter.
`update`	Document	The update to perform.
`arrayFilters`	Array of documents	(Optional) If you update an array-valued field, `arrayFilters` is a set of filters that specify which array elements an update applies to.
`hint`	Document or string	(Optional) The index to use for the operation.
`collation`	Document	(Optional) The collation to use when sorting results.
`upsert`	Boolean	Specifies whether MongoDB creates a new document if no document matches the filter. Defaults to `false`.

Replace One

{
   namespace: '<db>.<collection>',
   name: 'replaceOne',
   filter: Document,
   replacement: Document,
   hint?: Document | string,
   collation?: Document
}

Field	Type	Description
`namespace`	String	The database and collection that you want to replace documents in.
`name`	String	The operation. Set to `"replaceOne"` for a replace one operation.
`filter`	Document	The filter that matches the document you want to update. During a replace one operation, `mongosh` only replaces the first matching document.
`replacement`	Document	The replacement document.
`hint`	Document or string	(Optional) The index to use for the operation.
`collation`	Document	(Optional) The collation to use when sorting results.

Delete One or Many

{
   namespace: '<db>.<collection>',
   name: 'deleteOne' | 'deleteMany',
   filter: Document,
   hint?: Document | string,
   collation?: Document
}

Field	Type	Description
`namespace`	String	The database and collection that you want to delete documents in.
`name`	String	The operation. Set to `"deleteOne"` for a delete one operation. Set to `"deleteMany"` for a delete many operation.
`filter`	Document	The filter that matches the document you want to delete. During a delete one operation, `mongosh` only deletes the first matching document. During a delete many operation, `mongosh` deletes all matching documents.
`hint`	Document or string	(Optional) The index to use for the operation.
`collation`	Document	(Optional) The collation to use when sorting results.

Options

You can use the following options with bulkWrite(). You can pass a document to bulkWrite() that contains the options that you want to use. This document is optional.

{
   ordered?: boolean,
   verboseResults?: boolean,
   bypassDocumentValidation?: boolean,
   let?: Document
}

Field	Type	Description
`ordered`	Boolean	(Optional) Indicates that MongoDB performs the bulk write in order of the documents that you provide. Defaults to `true`.
`verboseResults`	Boolean	(Optional) Specifies if `bulkWrite()` outputs verbose results. Defaults to `false`.
`bypassDocumentValidation`	Boolean	(Optional) Specifies if the write operation bypasses document validation rules. Defaults to `false`.
`let`	Document	(Optional) Document of parameter names and values that you can access with aggregation variables.

Output

bulkWrite() returns an object with the following fields:

{
   acknowledged: boolean,
   insertedCount: int,
   matchedCount: int,
   modifiedCount: int,
   deletedCount: int,
   upsertedCount: int,
   insertResults?: map(int, document),
   updateResults?: map(int, document),
   deleteResults?: map(int, document)
}

Field	Type	Description
`acknowledged`	boolean	`true` if the server returns an acknowledgment, `false` otherwise.
`insertedCount`	integer	Number of documents inserted.
`matchedCount`	integer	Number of documents matched by filter.
`modifiedCount`	integer	Number of documents modified.
`deletedCount`	integer	Number of documents deleted.
`upsertedCount`	integer	Number of documents upserted.
`insertResults`	Map of integers to documents	Optional. Represents the results of each successful insert operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation. Document includes the following field: `insertedId`: ObjectID. Represents the `_id` of the inserted document.
`updateResults`	Map of integers to documents	Optional. Represents the results of each successful update operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation. Document includes the following fields: `matchedCount`: integer. Represents the number of documents matched. `modifiedCount`: integer. Represents the number of documents modified. `upsertedId`: ObjectID. Represents the `_id` of any upserted documents. Optional. `didUpsert`: boolean. `true` if a document was upserted, `false` otherwise.
`deleteResults`	Map of integers to documents	Optional. Represents the results of each successful delete operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation. Document includes the following field: `deletedCount`: integer. Represents the number of documents deleted.

Examples

This example uses Mongo.bulkWrite() to perform the following operations in order:

inserts a document into the db.authors collection
inserts a document into the db.books collection
updates the previous document

db.getMongo().bulkWrite(
   [
      {
         namespace: 'db.authors',
         name: 'insertOne',
         document: { name: 'Stephen King' }
      },
      {
         namespace: 'db.books',
         name: 'insertOne',
         document: { name: 'It' }
      },
      {
         namespace: 'db.books',
         name: 'updateOne',
         filter: { name: 'it' },
         update: { $set: { year: 1986 } }
      }
   ],
   {
      ordered: true,
      bypassDocumentValidation: true
   }
)

mongosh performs the bulk write in order and returns the following document:

{
   acknowledged: true,
   insertedCount: 2,
   matchedCount: 1,
   modifiedCount: 1,
   deletedCount: 0,
   upsertedCount: 0,
   insertResults: { '1': { insertedId: ObjectId('67ed8ce8efd926c84cab7945') },
                    '2': { insertedId: ObjectId('67ed8ce8efd926c84cab7946') } }
   updateResults: { '1': { matchedCount: 1, modifiedCount: 1, didUpsert: false } }
}

Back

db.collection.initializeUnorderedBulkOp

Bulk