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

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

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:

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)

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:

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)

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:

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.

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:

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)

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:

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