> ## Documentation Index
> Fetch the complete documentation index at: https://fpo-python.santosdev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Firestore Pydantic ODM: Async Python ODM for Firestore

> Firestore Pydantic ODM is an async, fully-typed Python ODM for Google Cloud Firestore. Define models with Pydantic, run queries, batch writes, and subcollections in minutes.

Firestore Pydantic ODM gives Python developers a clean, type-safe layer over Google Cloud Firestore. Define your data models as Pydantic classes, then use async CRUD methods, rich query filters, projections, subcollections, and atomic batch writes—all with zero boilerplate.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Connect to Firestore and run your first async query in under five minutes.
  </Card>

  <Card title="Installation" icon="box" href="/installation">
    Install via pip and set up credentials for production or the local emulator.
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts/models">
    Learn how models, the database client, and subcollections fit together.
  </Card>

  <Card title="API Reference" icon="code" href="/api/base-firestore-model">
    Full reference for every class, method, enum, and field descriptor.
  </Card>
</CardGroup>

## Why Firestore Pydantic ODM?

Firestore's native Python SDK is powerful but low-level: you work directly with dictionaries, manage document references by hand, and write your own serialization logic. Firestore Pydantic ODM sits on top of that SDK and gives you:

* **Pydantic validation** — every document is validated on read and write.
* **Async-first** — all I/O uses `async/await` with `google-cloud-firestore`'s `AsyncClient`.
* **Pythonic filters** — write `User.age >= 18` instead of string-based `where` clauses.
* **Projections** — define a lightweight Pydantic model to fetch only the fields you need.
* **Subcollections** — declare parent–child relationships directly in the model `Settings`.
* **Pydantic v1 & v2** — works transparently with either major version.

## Get started in three steps

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    pip install firestore-pydantic-odm
    ```
  </Step>

  <Step title="Define a model and initialise the database">
    ```python theme={null}
    from firestore_pydantic_odm import BaseFirestoreModel, FirestoreDB, init_firestore_odm

    class User(BaseFirestoreModel):
        class Settings:
            name = "users"   # Firestore collection name

        name: str
        email: str

    db = FirestoreDB(project_id="my-gcp-project")
    init_firestore_odm(db, [User])
    ```
  </Step>

  <Step title="Run async CRUD">
    ```python theme={null}
    import asyncio

    async def main():
        user = User(name="Alice", email="alice@example.com")
        await user.save()

        async for u in User.find(filters=[User.name == "Alice"]):
            print(u.email)

    asyncio.run(main())
    ```
  </Step>
</Steps>

<Tip>
  Use the [Firestore emulator](/guides/testing) for local development and CI. Pass `emulator_host="localhost:8080"` to `FirestoreDB` to route all traffic locally.
</Tip>