Bulk Write Operations

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.

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

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:

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

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

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:

• bulk_write()

• InsertOne

• UpdateOne

• UpdateMany

• ReplaceOne

• DeleteOne

• DeleteMany

• BulkWriteResult

• BulkWriteError