/ /

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.

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 on the the sample_mflix database.

inserts a document into the users collection
updates a document in the theaters collection
inserts another document into the users collection

db.getMongo().bulkWrite(
   [
      {
         namespace: 'sample_mflix.users',
         name: 'insertOne',
         document: { 
            name: 'Cersei Lannister',
            email: 'cersei.l@example.com',
            password: '$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu'
         }
      },
      {
         namespace: 'sample_mflix.theaters',
         name: 'updateOne',
         filter: { theaterId: 1000 },
         update: { $set: { 
            "location.address.street1": "350 W Market",
            "location.address.city": "Bloomington"
         } }
      },
      {
         namespace: 'sample_mflix.users',
         name: 'insertOne',
         document: { 
            name: 'Sansa Stark',
            email: 'sansa.s@example.com',
            password: '$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu'
         }
      }
   ],
   {
      ordered: true,
      bypassDocumentValidation: true,
      verboseResults: 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: Map(2) {
    0 => { insertedId: "..." },
    2 => { insertedId: "..." }
  },
  updateResults: Map(1) {
    1 => { matchedCount: 1, modifiedCount: 1, didUpsert: false }
  },
  deleteResults: Map(0) {}
}

Back

db.collection.initializeUnorderedBulkOp

Bulk