Skip to main content
Firestore Pydantic ODM bridges the gap between Pydantic’s powerful data-validation layer and Google Cloud Firestore’s scalable NoSQL backend. Define your collections as ordinary Pydantic models, and the library handles async CRUD, batch writes, transactions, subcollections, and field-masked projections—so your code stays clean, typed, and efficient.

​
What Is Firestore Pydantic ODM?

Firestore Pydantic ODM is an open-source Python library published by Santos Dev Co under the BSD-3-Clause license. It wraps the official google-cloud-firestore async client in an ODM layer driven entirely by Pydantic model definitions. Every document in a Firestore collection maps to a subclass of BaseFirestoreModel, which carries its collection name in an inner Settings class and inherits a full suite of async class methods for querying and writing data. The library auto-detects whether you are running Pydantic v1 or v2 at import time and adjusts its internal compatibility shims accordingly, so you can adopt it in any existing project without having to migrate your Pydantic version first.

​
Key Features

Async CRUD

Create, read, update, and delete Firestore documents with native async/await using save(), update(), delete(), and get().

Pydantic Validation

Define collections as Pydantic models and get automatic field validation, type coercion, and IDE auto-complete out of the box.

Advanced Querying

Filter, order, paginate, and project results with find() and find_one(). Projections generate Firestore field masks so only requested fields are fetched.

Batch Operations

Group multiple creates, updates, and deletes into a single atomic batch_write() call for consistency and lower RPC overhead.

Subcollections

Declare parent–child relationships with Settings.parent and traverse nested collections with the fluent subcollection() accessor.

Emulator & Testing

Switch to the Firestore emulator with a single argument, or replace the client with a MagicMock for fully isolated unit tests.

Projections

Pass any Pydantic BaseModel as a projection= argument to find() or find_one() to fetch only the fields you actually need.

Database Client

FirestoreDB wraps the async Firestore client and handles credential resolution, emulator toggling, and mock injection in one place.

​
Public API

All public names are importable directly from the top-level firestore_pydantic_odm package: 
from firestore_pydantic_odm import (
    BaseFirestoreModel,   # Base class for all Firestore document models
    FirestoreField,       # Field descriptor for custom Firestore field names/options
    FirestoreDB,          # Async Firestore client wrapper
    BatchOperation,       # Enum for batch write operations (CREATE, UPDATE, DELETE)
    FirestoreOperators,   # Enum of Firestore query operators (==, !=, <, >, etc.)
    OrderByDirection,     # Enum for sort direction (ASCENDING, DESCENDING)
    SubCollectionAccessor, # Fluent accessor returned by model.subcollection()
    init_firestore_odm,   # Recommended initializer — wires DB into all models at once
)
init_firestore_odm(db, [ModelA, ModelB, ...]) is the recommended way to initialize the library. It injects the FirestoreDB instance into every model and registers the full model graph so cascade deletes can be resolved automatically. Calling BaseFirestoreModel.initialize_db(db) directly on a single model class is also supported as a per-model alternative.

​
Requirements

Before installing, make sure your environment meets the following minimum requirements:
  • Python 3.8 or later — the library uses async/await throughout and requires the typing module features available from Python 3.8 onwards.
  • Pydantic v1 (>=1.5) or Pydantic v2 (<3.0.0) — both major versions are supported; the correct compatibility layer is selected automatically at runtime.
  • google-cloud-firestore>=2.11.0 — version 2.11.0 introduced the FieldFilter API that powers the query builder.

​
Pydantic v1 / v2 Compatibility

Firestore Pydantic ODM ships an internal pydantic_compat module that detects your installed Pydantic version at import time using the packaging library. All internal calls—model_dump, field introspection, ConfigDict—are routed through version-aware wrappers, so you never need to change your model definitions when upgrading Pydantic.
If you are running Pydantic v2, the library configures model_config = ConfigDict(populate_by_name=True) automatically. For Pydantic v1, the equivalent Config.allow_population_by_field_name = True is applied instead.

​
License

Firestore Pydantic ODM is distributed under the BSD-3-Clause License. See the LICENSE file in the repository for the full license text.