Insert Documents

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.

Example

The following code uses the insert_many() method to insert three new documents into a collection. Because the second method argument is bypass_document_validation = True, this insert operation bypasses document-level validation. Select the Synchronous or Asynchronous tab to see the corresponding code:

document_list = [
   { "name" : "Mongo's Burgers" },
   { "name" : "Mongo's Pizza" },
   { "name" : "Mongo's Tacos" }
]
sample_restaurants.restaurants.insert_many(document_list, bypass_document_validation = True)

document_list = [
   { "name" : "Mongo's Burgers" },
   { "name" : "Mongo's Pizza" },
   { "name" : "Mongo's Tacos" }
]
await sample_restaurants.restaurants.insert_many(document_list, bypass_document_validation = True)

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]]

You might see a similar error if you pass a list to the insert_one() method:

error: Argument 1 to "insert_one" of "Collection" has
incompatible type "List[Dict[<nothing>, <nothing>]]";
expected "Mapping[str, Any]"

This error occurs because the insert_one() method accepts a document, not a list. You can resolve this error by passing a document to the insert_one() method or by calling the insert_many() method instead.

TypedDict Missing _id Key

If you don't specify the _id field, PyMongo automatically inserts it into the document. You can retrieve the value of the _id field at runtime, but if you use MyPy or another tool to perform static type-checking, it won't find the _id field in your class and will show an error similar to the following:

TypedDict has no key "_id"

This is caused by code similar to the following:

from typing import TypedDict
from pymongo import MongoClient
from pymongo.collection import Collection
class Movie(TypedDict):
    name: str
    year: int
client: MongoClient = MongoClient()
collection: Collection[Movie] = client.test.test
inserted = collection.insert_one(Movie(name="Jurassic Park", year=1993))
result = collection.find_one({"name": "Jurassic Park"})
# _id is present but was added by PyMongo; this will raise a type-checking error
assert result["_id"]

One solution is to add a # type:ignore comment to the end of the line that uses the _id field. This comment instructs the type-checking tool to ignore any errors that the line causes. The following example shows how to implement this solution;

from typing import TypedDict
from pymongo import MongoClient
from pymongo.collection import Collection
class Movie(TypedDict):
    name: str
    year: int
collection: Collection[Movie] = client.test.test
inserted = collection.insert_one(
    Movie(name="Jurassic Park", year=1993)
)
result = collection.find_one({"name": "Jurassic Park"})
assert result is not None
assert result["_id"] # type:ignore[typeddict-item]

Instead of ignoring the type error, you can avoid it by including the _id field in your model class, and explicitly specifying a value for this field when you create the class instance. The following code shows how to implement this solution:

from typing import TypedDict
from pymongo import MongoClient
from pymongo.collection import Collection
from bson import ObjectId
class Movie(TypedDict):
    _id: ObjectId
    name: str
    year: int
collection: Collection[ExplicitMovie] = client.test.test
inserted = collection.insert_one(
    ExplicitMovie(_id=ObjectId(), name="Jurassic Park", year=1993)
)
result = collection.find_one({"name": "Jurassic Park"})
assert result is not None
assert result["_id"]

One drawback to adding the _id field to your custom class is that you must include a value for the field for every instance of the class that you create. To avoid this, you can install the typing.NotRequired package, which includes the NotRequired type hint. If you use this type hint for the _id field, you can access the value of the _id field at runtime without seeing any compile-time type errors.

The following code example shows how to implement this solution:

from typing import TypedDict, NotRequired
from pymongo import MongoClient
from pymongo.collection import Collection
from bson import ObjectId
class Movie(TypedDict):
     _id: NotRequired[ObjectId]
    name: str
    year: int
client: MongoClient = MongoClient()
collection: Collection[Movie] = client.test.test
inserted = collection.insert_one(Movie(name="Jurassic Park", year=1993))
result = collection.find_one({"name": "Jurassic Park"})
assert result is not None
assert result["_id"]

API Documentation

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

• insert_one()

• insert_many()

• ClientSession