/ /

CRUD Operations

Docs Home

/ /

Bulk Operations

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of the Node.js driver.

Overview

In this guide, you can learn how to use the Node.js driver to perform bulk operations. Bulk operations help reduce the number of calls to the server. Instead of sending a request for each operation, you can perform multiple operations within one action.

Tip

To learn more about bulk operations, see Bulk Write Operations in the MongoDB Server manual.

This guide includes the following sections:

Bulk Insert Operations describes how to perform bulk insert operations on your collection or client.
Bulk Replace Operations describes how to perform bulk replace operations on your collection or client.
Bulk Update Operations describes how to perform bulk update operations on your collection or client.
Bulk Delete Operations describes how to perform bulk delete operations on your collection or client.
Return Type describes the return object that results from your bulk write operations.
Handling Exceptions describes the exceptions that occur if any of the operations in a bulk write operation fail.
Additional Information provides links to resources and API documentation for types and methods mentioned in this guide.

Important

Server and Driver Version Requirements

Collection-level bulk write operations require the following versions:

MongoDB Server version 3.2 or later
Node.js driver version 3.6 or later

Sample Data

The examples in this guide use the movies and users collections in the sample_mflix database, which is included in the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Bulk Insert Operations

To perform a bulk insert operation, create a bulk operation model for each document you want to insert. Then, pass a list of these models to the bulkWrite() method.

Collection Bulk Inserts

To perform a bulk insert operation on your collection, create an InsertOneModel for each operation. Then, call the bulkWrite() method on your collection and pass an array of models as a parameter. To create an InsertOneModel, specify the model's document field and set it to the document you want to insert.

Example

This example performs the following actions:

Specifies two InsertOneModel instances in an array. Each InsertOneModel represents a document to insert into the movies collection in the sample_mflix database.
Calls the bulkWrite() method on the movies collection and passes an array of models as a parameter.
Prints the number of inserted documents.

Bulk Replace Operations

To perform a bulk replace operation, create a bulk operation model for each document you want to replace. Then, pass a list of these models to the bulkWrite() method.

Collection Bulk Replacements

To perform a bulk replace operation on your collection, create a ReplaceOneModel for each operation. Then, call the bulkWrite() method on your collection and pass an array of models as a parameter.

The following table describes the fields that you can set in a ReplaceOneModel:

Field	Description
`filter`	The filter that matches the document you want to replace. Type: `Document`
`replacement`	The replacement document. Type: `Document`
`collation`	(Optional) The collation to use when sorting results. To learn more about collations, see the Collations guide. Type: `String` or `Object`
`hint`	(Optional) The index to use for the operation. To learn more about indexes, see the Indexes on Collections guide. Type: `Bson`
`upsert`	(Optional) Whether a new document is created if no document matches the filter. By default, this field is set to `false`. Type: `Boolean`

Example

This example performs the following actions:

Specifies two ReplaceOneModel instances in an array. The ReplaceOneModel instances contain instructions to replace documents representing movies in the movies collection.
Calls the bulkWrite() method on the movies collection and passes an array of models as a parameter.
Prints the number of modified documents.

Bulk Update Operations

To perform a bulk update operation, create a bulk operation model for each update you want to make. Then, pass a list of these models to the bulkWrite() method.

Collection Bulk Updates

To perform a bulk update operation on your collection, create an UpdateOneModel or UpdateManyModel for each operation. Then, call the bulkWrite() method on your collection and pass an array of models as a parameter. An UpdateOneModel updates only one document that matches a filter, while an UpdateManyModel updates all documents that match a filter.

The following table describes the fields you can set in an UpdateOneModel or UpdateManyModel:

Field	Description
`filter`	The filter that matches one or more documents you want to update. When specified in an `UpdateOneModel`, only the first matching document will be updated. When specified in an `UpdateManyModel`, all matching documents will be updated. Type: `Document`
`update`	The update to perform. Type: `Document`
`arrayFilters`	(Optional) A set of filters specifying which array elements an update applies to if you are updating an array-valued field. Type: `Array`
`collation`	(Optional) The collation to use when sorting results. To learn more about collations, see the Collations guide. Type: `Object`
`hint`	(Optional) The index to use for the operation. To learn more about indexes, see the Indexes on Collections guide. Type: `String or Object`
`upsert`	(Optional) Whether a new document is created if no document matches the filter. By default, this field is set to `false`. Type: `Boolean`

Example

This example performs the following actions:

Specifies an UpdateOneModel and an UpdateManyModel instance in an array. These models contain instructions to update documents representing movies in the movies collection.
Calls the bulkWrite() method on the movies collection and passes an array of models as a parameter.
Prints the number of modified documents.

Bulk Delete Operations

To perform a bulk delete operation, create a bulk operation model for each delete operation. Then, pass a list of these models to the bulkWrite() method.

Collection Bulk Deletes

To perform a bulk delete operation on your collection, create a DeleteOneModel or DeleteManyModel for each operation. Then, call the bulkWrite() method on your collection and pass an array of models as a parameter. A DeleteOneModel deletes only one document that matches a filter, while a DeleteManyModel deletes all documents that match a filter.

The following table describes the fields you can set in a DeleteOneModel or DeleteManyModel:

Field	Description
`filter`	The filter that matches one or more documents you want to delete. When specified in a `DeleteOneModel`, only the first matching document will be deleted. When specified in a `DeleteManyModel`, all matching documents will be deleted. Type: `Document`
`collation`	(Optional) The collation to use when sorting results. To learn more about collations, see the Collations guide. Type: `Object`
`hint`	(Optional) The index to use for the operation. To learn more about indexes, see the Indexes on Collections guide. Type: `String or Object`

Example

This example performs the following actions:

Specifies a DeleteOneModel and a DeleteManyModel instance in an array. These models contain instructions to delete documents in the movies collection.
Calls the bulkWrite() method on the movies collection and passes an array of models as a parameter.
Prints the number of deleted documents.

Return Type

The Collection.bulkWrite() method returns a BulkWriteResult object, which provides information about your bulk operation.

The following tables describes the fields of a BulkWriteResult object:

Field	Description
`insertedCount`	The number of inserted documents
`matchedCount`	The number of matched documents
`modifiedCount`	The number of updated documents
`upsertedCount`	The number of upserted documents
`deletedCount`	The number of deleted documents

Handling Exceptions

If any bulk write operations called on a collection are unsuccessful, the Node.js driver throws a MongoBulkWriteError and does not perform any further operations if the ordered option is set to true. If ordered is set to false, it will attempt to continue with subsequent operations.

Tip

To learn more about ordered and unordered bulk operations, see the Ordered vs Unordered Operations section in the Bulk Write guide from the MongoDB Server manual.

A MongoBulkWriteError object contains the following properties:

Property	Description
`message`	The error message. Type: `String`
`writeErrors`	An array of errors that occurred during the bulk write operation. Type: `BulkWriteError[]`
`writeConcernErrors`	Write concern errors that occurred during execution of the bulk write operation. Type: `WriteConnectionError[]`
`result`	The results of any successful operations performed before the exception was thrown. Type: `BulkWriteResult[]`
`err`	The underlying error object, which may contain more details. Type: `Error`

Additional Information

To learn more about bulk operations, see Bulk Write Operations in the MongoDB Server manual.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Delete Documents

Compound Operations