Mongo.bulkWrite() (mongosh method)

Definition

Mongo.bulkWrite(operations, options)

Mongo.bulkWrite() performs multiple write operations across multiple databases and collections in a single call, unlike db.collection.bulkWrite() which operates on a single collection.

Note

Requires MongoDB 8.0 or later.

To use bulkWrite() in a multi-document transaction, call Session.bulkWrite(). It accepts the same parameters as Mongo.bulkWrite() and associates the operation with the session.

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 for the insert operation.
`name`	String	The operation name. Set to `"insertOne"`.
`document`	Document	The document to insert.

Note

If the document does not include an _id field, mongosh automatically generates one.

Update One and Update Many

updateOne updates the first document matching the filter. updateMany updates all documents matching the filter.

{
   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 for the update operation.
`name`	String	The operation name. Set to `"updateOne"` or `"updateMany"`.
`filter`	Document	The filter that matches one or more documents you want to update.
`update`	Document or array of documents	The update to perform.
`arrayFilters`	Array of documents	Optional. Filters to specify which array elements to update if you update an array-valued field.
`hint`	Document or string	Optional. The index to use for the operation.
`collation`	Document	(Optional) The collation to use when sorting results.
`upsert`	Boolean	Optional. If `true`, create a document if no match is found. 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 for the replace operation.
`name`	String	The operation name. Set to `"replaceOne"`.
`filter`	Document	The filter that matches the document you want to update.
`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

deleteOne deletes the first document matching the filter. deleteMany deletes all documents matching the filter.

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

Field	Type	Description
`namespace`	String	The database and collection for the delete operation.
`name`	String	The operation name. Set to `"deleteOne"` or `"deleteMany"`.
`filter`	Document	The query selector to match documents to delete.
`hint`	Document or string	Optional. The index to use for the operation.
`collation`	Document	Optional. The collation to use for the operation.

Options

{
   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. If `true`, stops on the first error. If `false`, continues processing the remaining operations even if some operations fail. 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