Bulk Write Operations

Sample Data

The examples in this guide use the sample_restaurants.restaurants and sample_mflix.movies collections 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.

Insert Operations

To perform an insert operation, create an instance of InsertOne and specify the document you want to insert. Pass the following keyword arguments to the InsertOne constructor:

• namespace: The namespace in which to insert the document. This argument is optional if you perform the bulk operation on a single collection.

• document: The document to insert.

The following example creates an instance of InsertOne:

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

You can also create an instance of InsertOne by passing an instance of a custom class to the constructor. This provides additional type safety if you're using a type-checking tool. The instance you pass must inherit from the TypedDict class.

The following example constructs an InsertOne instance by using a custom class for added type safety:

class Restaurant (TypedDict):
    name: str
    cuisine: str
    borough: str
    restaurant_id: str
operation = pymongo.InsertOne(Restaurant(
    name="Mongo's Deli", cuisine="Sandwiches", borough="Manhattan", restaurant_id="1234"))

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

Update Operations

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

• namespace: The namespace in which to perform the update. This argument is optional if you perform the bulk operation on a single collection.

• filter: The query filter that specifies the criteria used to match documents in your collection.

• update: The update 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 = UpdateOne(
    namespace="sample_restaurants.restaurants",
    filter={ "name": "Mongo's Deli" },
    update={ "$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 = UpdateMany(
    namespace="sample_restaurants.restaurants",
    filter={ "name": "Mongo's Deli" },
    update={ "$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 in the following arguments:

• namespace: The namespace in which to perform the replace operation. This argument is optional if you perform the bulk operation on a single collection.

• filter: The query filter that specifies the criteria used to match the document to replace.

• replacement: The document that includes the new fields and values you want to store in the matching document.

The following example creates an instance of ReplaceOne:

operation = ReplaceOne(
    namespace="sample_restaurants.restaurants",
    filter={ "restaurant_id": "1234" },
    replacement={
        "name": "Mongo's Pizza",
        "cuisine": "Pizza",
        "borough": "Brooklyn",
        "restaurant_id": "5678"
    }
)

You can also create an instance of ReplaceOne by passing an instance of a custom class to the constructor. This provides additional type safety if you're using a type-checking tool. The instance you pass must inherit from the TypedDict class.

The following example constructs a ReplaceOne instance by using a custom class for added type safety:

class Restaurant (TypedDict):
    name: str
    cuisine: str
    borough: str
    restaurant_id: str
operation = pymongo.ReplaceOne(
    { "restaurant_id": "1234" },
    Restaurant(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 the following arguments:

• namespace: The namespace in which to delete the document. This argument is optional if you perform the bulk operation on a single collection.

• filter: The query filter that specifies the criteria used to match the document to delete.

DeleteOne removes only the first document that matches your query filter.

The following example creates an instance of DeleteOne:

operation = DeleteOne(
    namespace="sample_restaurants.restaurants",
    filter={ "restaurant_id": "5678" }
)

To delete multiple documents, create an instance of DeleteMany and pass in a namespace and 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 = DeleteMany(
    namespace="sample_restaurants.restaurants",
    filter={ "name": "Mongo's Deli" }
)

Collection Bulk Write Example

The following example performs multiple write operations on the restaurants collection by using the bulk_write() method on a Collection instance. Select the Synchronous or Asynchronous tab to see the corresponding code:

operations = [
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Manhattan",
            "restaurant_id": "1234"
        }
    ),
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Brooklyn",
            "restaurant_id": "5678"
        }
    ),
    UpdateMany(
        filter={ "name": "Mongo's Deli" },
        update={ "$set": { "cuisine": "Sandwiches and Salads" }}
    ),
    DeleteOne(
        filter={ "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)

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

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

Client Bulk Write Example

The following example performs multiple write operations on the sample_restaurants.restaurants and sample_mflix.movies namespaces by using the bulk_write() method on a MongoClient instance. Select the Synchronous or Asynchronous tab to see the corresponding code:

operations = [
    InsertOne(
        namespace="sample_mflix.movies",
        document={
            "title": "Minari",
            "runtime": 217,
            "genres": ["Drama", "Comedy"]
        }
    ),
    UpdateOne(
        namespace="sample_mflix.movies",
        filter={ "title": "Minari" },
        update={ "$set": { "runtime": 117 }}
    ),
    DeleteMany(
        namespace="sample_restaurants.restaurants",
        filter={ "cuisine": "French" }
    )
]
results = client.bulk_write(operations)
print(results)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1,
'nModified': 1, 'nDeleted': 344, 'insertResults': {}, 'updateResults': {},
'deleteResults': {}}, acknowledged=True, verbose=False)

operations = [
    InsertOne(
        namespace="sample_mflix.movies",
        document={
            "title": "Minari",
            "runtime": 217,
            "genres": ["Drama", "Comedy"]
        }
    ),
    UpdateOne(
        namespace="sample_mflix.movies",
        filter={ "title": "Minari" },
        update={ "$set": { "runtime": 117 }}
    ),
    DeleteMany(
        namespace="sample_restaurants.restaurants",
        filter={ "cuisine": "French" }
    )
]
results = await client.bulk_write(operations)
print(results)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1,
'nModified': 1, 'nDeleted': 344, 'insertResults': {}, 'updateResults': {},
'deleteResults': {}}, acknowledged=True, verbose=False)

Collection Bulk Write Options

The following table describes the options you can pass to the Collection.bulk_write() method:

The following example calls the bulk_write() method from the preceding Collection Bulk Write Example but sets the ordered option to False. Select the Synchronous or Asynchronous tab to see the corresponding code:

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

results = await 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.

Client Bulk Write Options

The following table describes the options you can pass to the MongoClient.bulk_write() method:

The following example calls the bulk_write() method from the preceding Client Bulk Write Example but sets the verbose_results option to True. Select the Synchronous or Asynchronous tab to see the corresponding code:

results = client.bulk_write(operations, verbose_results=True)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1, 'nModified': 1,
'nDeleted': 344, 'insertResults': {0: InsertOneResult(ObjectId('...'),
acknowledged=True)}, 'updateResults': {1: UpdateResult({'ok': 1.0, 'idx': 1, 'n': 1,
'nModified': 1}, acknowledged=True)}, 'deleteResults': {2: DeleteResult({'ok': 1.0,
'idx': 2, 'n': 344}, acknowledged=True)}}, acknowledged=True, verbose=True)

results = await client.bulk_write(operations, verbose_results=True)

ClientBulkWriteResult({'anySuccessful': True, 'error': None, 'writeErrors': [],
'writeConcernErrors': [], 'nInserted': 1, 'nUpserted': 0, 'nMatched': 1, 'nModified': 1,
'nDeleted': 344, 'insertResults': {0: InsertOneResult(ObjectId('...'),
acknowledged=True)}, 'updateResults': {1: UpdateResult({'ok': 1.0, 'idx': 1, 'n': 1,
'nModified': 1}, acknowledged=True)}, 'deleteResults': {2: DeleteResult({'ok': 1.0,
'idx': 2, 'n': 344}, acknowledged=True)}}, acknowledged=True, verbose=True)

Collection Bulk Write Return Value

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

Client Bulk Write Return Value

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

Client Type Annotations

If you don't add a type annotation for your MongoClient object, your type checker might show an error similar to the following:

from pymongo import MongoClient
client = MongoClient()  # error: Need type annotation for "client"

The solution is to annotate the MongoClient object as client: MongoClient or client: MongoClient[Dict[str, Any]].

Incompatible Type

If you specify MongoClient as a type hint but don't include data types for the document, keys, and values, your type checker might show an error similar to the following:

error: Dict entry 0 has incompatible type "str": "int";
expected "Mapping[str, Any]": "int"

The solution is to add the following type hint to your MongoClient object:

client: MongoClient[Dict[str, Any]]

API Documentation

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

• Collection.bulk_write()

• MongoClient.bulk_write()

• InsertOne

• UpdateOne

• UpdateMany

• ReplaceOne

• DeleteOne

• DeleteMany

• BulkWriteResult

• ClientBulkWriteResult

• BulkWriteError

• ClientBulkWriteException