Databases and Collections

Time Series Collection

Time series collections efficiently store sequences of measurements over a period of time. The following example creates a time series collection called example_ts_collection in which the documents' time field is called timestamp. Select the Synchronous or Asynchronous tab to see the corresponding code:

database = client["test_database"]
database.create_collection("example_ts_collection", timeseries={"timeField": "timestamp"})

database = client["test_database"]
await database.create_collection("example_ts_collection", timeseries={"timeField": "timestamp"})

For more information about using time series data with PyMongo, see the Time Series Data guide.

Capped Collection

You can create a capped collection that cannot grow beyond a specified memory size or document count. The following example creates a capped collection called example_capped_collection that has a maximum size of 1000 bytes. Select the Synchronous or Asynchronous tab to see the corresponding code:

database = client["test_database"]
database.create_collection("example_capped_collection", capped=True, size=1000)

database = client["test_database"]
await database.create_collection("example_capped_collection", capped=True, size=1000)

To learn more about capped collections, see Capped Collections in the MongoDB Server manual.

Database

If all documents in a database match a well-defined schema, you can specify a type hint that uses a Python class to represent the documents' structure. By including this class in the type hint for your Database object, you can ensure that all documents you store or retrieve have the required structure. This provides more accurate type checking and code completion than the default Dict[str, Any] type.

First, define a class to represent a document from the database. The class must inherit from the TypedDict class and must contain the same fields as the documents in the database. After you define your class, include its name as the generic type for the Database type hint.

The following example defines a Movie class and uses it as the generic type for a Database type hint. Select the Synchronous or Asynchronous tab to see the corresponding code:

from typing import TypedDict
from pymongo import MongoClient
from pymongo.database import Database
class Movie(TypedDict):
 name: str
 year: int
client: MongoClient = MongoClient()
database: Database[Movie] = client["test_database"]

from typing import TypedDict
from pymongo import AsyncMongoClient
from pymongo.asynchronous.database import Database
class Movie(TypedDict):
 name: str
 year: int
client: AsyncMongoClient = AsyncMongoClient()
database: Database[Movie] = client["test_database"]

Collection

Adding a generic type to a Collection type hint is similar to adding a generic type to a Database type hint. First, define a class that inherits from the TypedDict class and represents the structure of the documents in the collection. Then, include the class name as the generic type for the Collection type hint, as shown in the following example. Select the Synchronous or Asynchronous tab to see the corresponding code:

from typing import TypedDict
from pymongo import MongoClient
from pymongo.asynchronous.collection import Collection
class Movie(TypedDict):
 name: str
 year: int
client: MongoClient = MongoClient()
database = client["test_database"]
collection: Collection[Movie] = database["test_collection"]

from typing import TypedDict
from pymongo import AsyncMongoClient
from pymongo.collection import Collection
class Movie(TypedDict):
 name: str
 year: int
client: AsyncMongoClient = AsyncMongoClient()
database = client["test_database"]
collection: Collection[Movie] = database["test_collection"]

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

AutoReconnect Error

You receive this error if you specify tag-sets in your read preference and MongoDB is unable to find replica set members with the specified tags. To avoid this error, include an empty dictionary ({}) at the end of the tag-set list. This instructs PyMongo to read from any member that matches the read-reference mode when it can't find matching tags.