Bulk Write Operations

On this page

Overview

Sample Data
Define the Write Operations
Insert Operations
Update Operations
Replace Operations
Delete Operations
Call the bulk_write() Method
Customize Bulk Write Operations
Return Value
Additional Information
API Documentation

Overview

Consider a scenario in which you want to insert a document into a collection, update multiple other documents, then delete a document. If you use individual methods, each operation requires its own database call. This guide shows you how to use bulk write operations to perform multiple write operations in a single database call.

Sample Data

The examples in this guide use the sample_restaurants.restaurants collection from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with PyMongo tutorial.

Define the Write Operations

For each write operation you want to perform, create an instance of one of the following operation classes:

InsertOne
UpdateOne
UpdateMany
ReplaceOne
DeleteOne
DeleteMany

Then, pass a list of these instances to the bulk_write() method.

The following sections show how to create and use instances of the preceding classes.

Insert Operations

To perform an insert operation, create an instance of InsertOne and specify the document you want to insert.

The following example creates an instance of InsertOne:

operation = pymongo.InsertOne(
    {
        "name": "Mongo's Deli",
        "cuisine": "Sandwiches",
        "borough": "Manhattan",
        "restaurant_id": "1234"
    }
)

To insert multiple documents, create an instance of InsertOne for each document.

Note

Duplicate _id values violate unique index constraints, which causes the driver to return a DuplicateKeyError. To avoid this error, ensure that each document you insert has a unique _id value.

Update Operations

To update a document, create an instance of UpdateOne and pass in the following arguments:

A query filter that specifies the criteria used to match documents in your collection
The update operation you want to perform. For more information about update operations, see the Field Update Operators guide in the MongoDB Server manual.

UpdateOne updates the first document that matches your query filter.

The following example creates an instance of UpdateOne:

operation = pymongo.UpdateOne(
    { "name": "Mongo's Deli" },
    { "$set": { "cuisine": "Sandwiches and Salads" }},
)

To update multiple documents, create an instance of UpdateMany and pass in the same arguments. UpdateMany updates all documents that match your query filter.

The following example creates an instance of UpdateMany:

operation = pymongo.UpdateMany(
    { "name": "Mongo's Deli" },
    { "$set": { "cuisine": "Sandwiches and Salads" }},
)

Replace Operations

A replace operation removes all fields and values of a specified document and replaces them with new ones. To perform a replace operation, create an instance of ReplaceOne and pass it a query filter and the fields and values you want to store in the matching document.

The following example creates an instance of ReplaceOne:

operation = pymongo.ReplaceOne(
    { "restaurant_id": "1234" },
    {
        "name": "Mongo's Pizza",
        "cuisine": "Pizza",
        "borough": "Brooklyn",
        "restaurant_id": "5678"
    }
)

To replace multiple documents, you must create an instance of ReplaceOne for each document.

Delete Operations

To delete a document, create an instance of DeleteOne and pass in a query filter specifying the document you want to delete. DeleteOne removes only the first document that matches your query filter.

The following example creates an instance of DeleteOne:

operation = pymongo.DeleteOne({ "restaurant_id": "5678" })

To delete multiple documents, create an instance of DeleteMany and pass in a query filter specifying the document you want to delete. DeleteMany removes all documents that match your query filter.

The following example creates an instance of DeleteMany:

operation = pymongo.DeleteMany({ "name": "Mongo's Deli" })

Call the `bulk_write()` Method

After you define a class instance for each operation you want to perform, pass a list of these instances to the bulk_write() method. By default, the method runs the operations in the order they're defined in the list.

The following example performs multiple write operations by using the bulk_write() method:

operations = [
    pymongo.InsertOne(
        {
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Manhattan",
            "restaurant_id": "1234"
        }
    ),
    pymongo.InsertOne(
        {
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Brooklyn",
            "restaurant_id": "5678"
        }
    ),
    pymongo.UpdateMany(
        { "name": "Mongo's Deli" },
        { "$set": { "cuisine": "Sandwiches and Salads" }},
    ),
    pymongo.DeleteOne(
        { "restaurant_id": "1234" }
    )
]
results = restaurants.bulk_write(operations)
print(results)

BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []}, acknowledged=True)

If any of the write operations fail, PyMongo raises a BulkWriteError and does not perform any further operations. BulkWriteError provides a details attribute that includes the operation that failed, and details about the exception.

Note

When PyMongo runs a bulk operation, it uses the write_concern of the collection in which the operation is running. The driver reports all write concern errors after attempting all operations, regardless of execution order.

Customize Bulk Write Operations

The bulk_write() method optionally accepts additional parameters, which represent options you can use to configure the bulk write operation. If you don't specify any additional options, the driver does not customize the bulk write operation.

Property	Description
`ordered`	If `True`, the driver performs the write operations in the order provided. If an error occurs, the remaining operations are not attempted. If `False`, the driver performs the operations in an arbitrary order and attempts to perform all operations. Defaults to `True`.
`bypass_document_validation`	Specifies whether the operation bypasses document-level validation. For more information, see Schema Validation in the MongoDB Server manual. Defaults to `False`.
`session`	An instance of `ClientSession`. For more information, see the API documentation.
`comment`	A comment to attach to the operation. For more information, see the delete command fields guide in the MongoDB Server manual.
`let`	A map of parameter names and values. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.

The following example calls the bulk_write() method from the preceding example, with the ordered option set to False:

results = restaurants.bulk_write(operations, ordered=False)

If any of the write operations in an unordered bulk write fail, PyMongo reports the errors only after attempting all operations.

Note

Unordered bulk operations do not guarantee order of execution. The order can differ from the way you list them to optimize the runtime.

Return Value

The bulk_write() method returns a BulkWriteResult object. The BulkWriteResult object contains the following properties:

Property	Description
`acknowledged`	Indicates if the server acknowledged the write operation.
`bulk_api_result`	The raw bulk API result returned by the server.
`deleted_count`	The number of documents deleted, if any.
`inserted_count`	The number of documents inserted, if any.
`matched_count`	The number of documents matched for an update, if applicable.
`modified_count`	The number of documents modified, if any.
`upserted_count`	The number of documents upserted, if any.
`upserted_ids`	A map of the operation's index to the `_id` of the upserted documents, if applicable.

Additional Information

To learn how to perform individual write operations, 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

Delete

Store Large Files

Overview

Sample Data

Define the Write Operations

Insert Operations

Note

Update Operations

Replace Operations

Delete Operations

Call the bulk_write() Method

Note

Customize Bulk Write Operations

Note

Return Value

Additional Information

API Documentation

Call the `bulk_write()` Method