Bulk Operations

On this page

Overview

Sample Data
Bulk Write
Modify Behavior
Return Values
Operations
Insert
Replace
Update
Delete
Execution Order
Ordered
Unordered
Additional Information
Related Operations
API Documentation

Overview

In this guide, you can learn how to use bulk operations.

Bulk operations perform a large number of write operations. Instead of making a call for each operation to the database, bulk operations perform multiple operations with one call to the database.

Sample Data

The examples in this guide use the following Book struct as a model for documents in the books collection:

type Book struct {
	Title  string
	Author string
	Length int32
}

To run the examples in this guide, load the sample data into the db.books collection with the following snippet:

coll := client.Database("db").Collection("books")
docs := []interface{}{
	Book{Title: "My Brilliant Friend", Author: "Elena Ferrante", Length: 331},
	Book{Title: "Lucy", Author: "Jamaica Kincaid", Length: 103},
}
result, err := coll.InsertMany(context.TODO(), docs)

Each document contains a description of a book that includes the title, author, and page length corresponding to the title, author, and length fields in each document.

Tip

Nonexistent Databases and Collections

If the necessary database and collection don't exist when you perform a write operation, the server implicitly creates them.

Bulk Write

To perform a bulk operation, pass an array of WriteModel documents to the BulkWrite() method.

Modify Behavior

The BulkWrite() method optionally takes a BulkWriteOptions type, which represents options you can use to modify its behavior. If you don't specify a BulkWriteOptions, the driver uses the default values for each option.

The BulkWriteOptions type allows you to configure options with the following methods:

Method	Description
`SetBypassDocumentValidation()`	Whether to allow the write to opt-out of document level validation. Default: `false`
`SetOrdered()`	Whether to stop performing write operations after an error occurs. Default: `true`

Return Values

The BulkWrite() method returns a BulkWriteResult type, which contains information about the bulk operation if it's successful. The BulkWriteResult type contains the following properties:

Property	Description
`InsertedCount`	The number of documents inserted.
`MatchedCount`	The number of documents matched by the query filter in update and replace operations.
`ModifiedCount`	The number of documents modified by update and replace operations.
`DeletedCount`	The number of documents deleted.
`UpsertedCount`	The number of documents upserted by update and replace operations.
`UpsertedIDs`	A map of an operation index to the `_id` of each upserted document.

Operations

A WriteModel represents an insert, replace, update, or delete operation.

Insert

To perform an insert operation, create an InsertOneModel specifying the document you want to insert. To insert multiple documents, create an InsertOneModel for each document you want to insert.

The InsertOneModel allows you to specify its behavior with the following method:

Method	Description
`SetDocument()`	The document to insert.

Example

This following example creates two InsertOneModel instances to insert two documents:

models := []mongo.WriteModel{
	mongo.NewInsertOneModel().SetDocument(Book{Title: "Beloved", Author: "Toni Morrison", Length: 324}),
	mongo.NewInsertOneModel().SetDocument(Book{Title: "Outline", Author: "Rachel Cusk", Length: 258}),
}

Replace

To perform a replace operation, create a ReplaceOneModel specifying the document you want to replace and a replacement document. To replace multiple documents, create a ReplaceOneModel for each document you want to replace.

The ReplaceOneModel allows you to specify its behavior with the following methods:

Method	Description
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to replace.
`SetHint()`	The index to use to scan for documents.
`SetReplacement()`	The document to replace the matched document with.
`SetUpsert()`	Whether to insert a new document if the query filter doesn't match any documents.

Example

The following example creates a ReplaceOneModel to replace a document where the title is "Lucy" with a new document:

models := []mongo.WriteModel{
	mongo.NewReplaceOneModel().SetFilter(bson.D{{"title", "Lucy"}}).
		SetReplacement(Book{Title: "On Beauty", Author: "Zadie Smith", Length: 473}),
}

Update

To perform an update operation, create an UpdateOneModel specifying the document you want to update and an update document. To update multiple documents, use the UpdateManyModel.

The UpdateOneModel and UpdateManyModel allow you to specify their behavior with the following methods:

Method	Description
`SetArrayFilters()`	The array elements the update applies to.
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to update.
`SetHint()`	The index to use to scan for documents.
`SetUpdate()`	The modifications to apply on the matched documents.
`SetUpsert()`	Whether to insert a new document if the query filter doesn't match any documents.

Example

The following example creates an UpdateOneModel to decrement a document's length by 15 if the author is "Elena Ferrante":

models := []mongo.WriteModel{
	mongo.NewUpdateOneModel().SetFilter(bson.D{{"author", "Elena Ferrante"}}).
		SetUpdate(bson.D{{"$inc", bson.D{{"length", -15}}}}),
}

Delete

To perform a delete operation, create a DeleteOneModel specifying the document you want to delete. To delete multiple documents, use the DeleteManyModel.

The DeleteOneModel and DeleteManyModel allow you to specify their behavior with the following methods:

Method	Description
`SetCollation()`	The type of language collation to use when sorting results.
`SetFilter()`	The query filter specifying which document to delete.
`SetHint()`	The index to use to scan for documents.

Example

The following example creates a DeleteManyModel to delete documents where the length is greater than 300:

models := []mongo.WriteModel{
	mongo.NewDeleteManyModel().SetFilter(bson.D{{"length", bson.D{{"$gt", 300}}}}),
}

Execution Order

The BulkWrite() method allows you to specify if you want to execute the bulk operations as ordered or unordered in its BulkWriteOptions.

Ordered

By default, the BulkWrite() method executes bulk operations in order you added them and stops if an error occurs.

Tip

This is equivalent to specifying true in the SetOrdered() method:

opts := options.BulkWrite().SetOrdered(true)

Unordered

To execute bulk write operations in any order and continue if an error occurs, specify false to the SetOrdered() method. The method reports the errors afterward.

Example

The following example performs the following actions in any order:

Inserts two documents.
Replaces a document where the title is "My Brilliant Friend" with a new document.
Increments every document's length by 10 if the current length value is less than 200.
Deletes all documents where the author field value includes "Jam".

models := []mongo.WriteModel{
  mongo.NewInsertOneModel().SetDocument(Book{Title: "Middlemarch", Author: "George Eliot", Length: 904}),
  mongo.NewInsertOneModel().SetDocument(Book{Title: "Pale Fire", Author: "Vladimir Nabokov", Length: 246}),
  mongo.NewReplaceOneModel().SetFilter(bson.D{{"title", "My Brilliant Friend"}}).
    SetReplacement(Book{Title: "Atonement", Author: "Ian McEwan", Length: 351}),
  mongo.NewUpdateManyModel().SetFilter(bson.D{{"length", bson.D{{"$lt", 200}}}}).
    SetUpdate(bson.D{{"$inc", bson.D{{"length", 10}}}}),
  mongo.NewDeleteManyModel().SetFilter(bson.D{{"author", bson.D{{"$regex", "Jam"}}}}),
}
opts := options.BulkWrite().SetOrdered(false)
results, err := coll.BulkWrite(context.TODO(), models, opts)
if err != nil {
   panic(err)
}
fmt.Printf("Number of documents inserted: %d\n", results.InsertedCount)
fmt.Printf("Number of documents replaced or updated: %d\n", results.ModifiedCount)
fmt.Printf("Number of documents deleted: %d\n", results.DeletedCount)

Number of documents inserted: 2
Number of documents replaced or updated: 2
Number of documents deleted: 1

The following documents are present in the books collection after the bulk operation:

{"title":"Atonement","author":"Ian McEwan","length":351}
{"title":"Middlemarch","author":"George Eliot","length":904}
{"title":"Pale Fire","author":"Vladimir Nabokov","length":246}

Additional Information

For a runnable example on performing a bulk operation, see Perform Bulk Operations.

Related Operations

To learn more about performing the operations mentioned, see the following guides:

API Documentation

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

Back

Upsert

Compound Operations