Docs Menu

Docs HomeGo

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

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.

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

Non-existent Databases and Collections

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

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

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

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.

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

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.

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}),
}

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.

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}),
}

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.

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}}}}),
}

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.

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}}}}),
}

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

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)

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 afterwards.

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)

The following documents are present in the ratings 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}

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

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

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

←  Insert or Update in a Single OperationCompound Operations →