0Pricing
FastAPI Backend Development Bootcamp · Lekcja

Modelowanie dokumentów za pomocą Beanie ODM

Definiuj typowane modele dokumentów, indeksy i struktury osadzone za pomocą Beanie opartego na Pydantic.

Modelowanie dokumentów za pomocą Beanie ODM to bezpłatna lekcja FastAPI Backend Development Bootcamp na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej FastAPI Backend Development Bootcamp, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs FastAPI Backend Development Bootcamp zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

What Beanie Brings to FastAPI

Beanie is an asynchronous ODM (Object-Document Mapper) for MongoDB built directly on top of Pydantic and the async motor driver. In a FastAPI backend it gives you typed, validated documents that feel just like the Pydantic models you already use for request and response bodies.

  • Each document class maps to one MongoDB collection.
  • Each instance maps to one document (a JSON-like record).
  • Validation, serialization, and JSON Schema come for free from Pydantic v2.

Because everything is async, Beanie pairs naturally with FastAPI's async route handlers and avoids blocking the event loop on database I/O.

Your First Document Model

A Beanie model subclasses Document instead of Pydantic's BaseModel. Fields are declared with normal type hints, and Beanie automatically gives every document an id field backed by MongoDB's _id (an ObjectId).

  • Required fields have no default; optional fields use Optional[...] or a default value.
  • The collection name is derived from the class name unless you override it.

Below, Product becomes a collection of product documents.

from typing import Optional
from beanie import Document


class Product(Document):
    name: str
    price: float
    description: Optional[str] = None
    in_stock: bool = True


# An instance is just a validated Pydantic object until you insert it
item = Product(name="Keyboard", price=49.9)
print(item.name, item.price, item.in_stock)

Configuring the Collection with Settings

Beanie reads optional configuration from an inner class Settings. The most common option is name, which sets the MongoDB collection name explicitly instead of relying on the class name.

  • name — the collection name.
  • use_state_management — track changed fields for partial saves.
  • validate_on_save — re-run validation when saving an existing document.

Pinning the collection name keeps your schema stable even if you later rename the Python class.

from beanie import Document


class Product(Document):
    name: str
    price: float

    class Settings:
        name = "products"
        validate_on_save = True


print(Product.Settings.name)

Initializing Beanie at App Startup

Before any document can talk to MongoDB you must call init_beanie once, passing your motor database and the list of document models. In FastAPI this belongs in the lifespan handler so it runs at startup.

  • AsyncIOMotorClient creates the async connection.
  • document_models registers every model so Beanie can build indexes and queries.

This is framework/server wiring — it needs a live MongoDB, so treat it as a setup pattern, not a standalone script.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from motor.motor_asyncio import AsyncIOMotorClient
from beanie import init_beanie


@asynccontextmanager
async def lifespan(app: FastAPI):
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    await init_beanie(
        database=client.shop_db,
        document_models=[Product],
    )
    yield
    client.close()


app = FastAPI(lifespan=lifespan)

Field Validation with Pydantic

Because a Document is a Pydantic model, every validation tool you know still works: Field constraints, custom validators, and rich types like EmailStr or HttpUrl.

  • Field(gt=0) rejects non-positive prices.
  • Field(min_length=...) enforces string length.
  • Validation runs when the object is constructed, so bad data never reaches MongoDB.

This snippet is pure Pydantic-style validation and runs on its own.

from pydantic import BaseModel, Field, ValidationError


class Product(BaseModel):
    name: str = Field(min_length=1, max_length=80)
    price: float = Field(gt=0)
    sku: str = Field(pattern=r"^[A-Z]{3}-\d{4}$")


try:
    Product(name="Mouse", price=-5, sku="bad")
except ValidationError as e:
    print("Rejected:", len(e.errors()), "errors")

good = Product(name="Mouse", price=19.99, sku="MOU-0001")
print("Accepted:", good.sku)

Declaring Indexes with Indexed

Indexes make queries fast and can enforce uniqueness. Beanie offers two styles. The simplest is the Indexed wrapper applied to a field's type, which creates a single-field index.

  • Indexed(str, unique=True) builds a unique index — perfect for an email or SKU.
  • Beanie creates the index automatically during init_beanie.

Use unique indexes to push integrity rules down into the database rather than relying only on app checks.

import pymongo
from beanie import Document, Indexed
from pydantic import EmailStr


class User(Document):
    email: Indexed(EmailStr, unique=True)
    username: Indexed(str)
    age: int

    class Settings:
        name = "users"

Compound Indexes in Settings

For multi-field or advanced indexes, declare them in Settings.indexes using PyMongo's IndexModel. This is how you build compound indexes, control sort direction, or add a TTL.

  • List the fields with directions: pymongo.ASCENDING / DESCENDING.
  • Pass unique=True or expireAfterSeconds=... through the IndexModel.

Order matters: a compound index on (category, price) optimizes queries that filter by category and then sort by price.

import pymongo
from pymongo import IndexModel
from beanie import Document


class Product(Document):
    name: str
    category: str
    price: float

    class Settings:
        name = "products"
        indexes = [
            IndexModel(
                [("category", pymongo.ASCENDING), ("price", pymongo.DESCENDING)],
                name="category_price_idx",
            ),
        ]

Embedded Documents with BaseModel

MongoDB stores nested objects inside a single document. In Beanie an embedded structure is just a plain Pydantic BaseModel used as a field type — it is not a separate collection and has no id.

  • Embed when the nested data is owned by the parent and always read together (an address inside a user).
  • The whole structure is validated and serialized as one document.

Here Address is embedded inside the User document.

from pydantic import BaseModel
from beanie import Document


class Address(BaseModel):
    street: str
    city: str
    postal_code: str


class User(Document):
    name: str
    address: Address

    class Settings:
        name = "users"


u = User(name="Ada", address=Address(street="1 Main", city="Oslo", postal_code="0150"))
print(u.address.city)

Lists of Embedded Structures

A document field can hold a list of embedded models, which is ideal for one-to-many data that belongs entirely to the parent — think order line items or comments.

  • list[OrderItem] validates every element on construction.
  • Each item is serialized inline, so reading the order needs no extra query.

Prefer embedding lists when the collection is bounded and read with the parent; use references when it grows unbounded.

from pydantic import BaseModel
from beanie import Document


class OrderItem(BaseModel):
    product_name: str
    quantity: int
    unit_price: float


class Order(Document):
    customer: str
    items: list[OrderItem]

    class Settings:
        name = "orders"

    @property
    def total(self) -> float:
        return sum(i.quantity * i.unit_price for i in self.items)


order = Order(
    customer="Lin",
    items=[OrderItem(product_name="Pen", quantity=3, unit_price=1.5)],
)
print(order.total)

Referencing Other Documents with Link

When related data lives in its own collection and is shared or large, use a reference instead of embedding. Beanie's Link[OtherDocument] stores a pointer (a DBRef) and can fetch the linked document on demand.

  • Link[Category] keeps the category in its own collection.
  • Use fetch_links=True on a query, or await doc.fetch_link(...), to resolve it.

Rule of thumb: embed owned, read-together data; link shared or independently-queried data.

from beanie import Document, Link


class Category(Document):
    name: str

    class Settings:
        name = "categories"


class Product(Document):
    name: str
    price: float
    category: Link[Category]

    class Settings:
        name = "products"

Modeling Choices: Embed vs Reference

The core design decision in document modeling is whether to embed data or reference it. There is no universal answer — it depends on access patterns and data size.

  • Embed when: the child is owned by the parent, always loaded together, and bounded in size (address, order items).
  • Reference when: the data is shared across documents, queried on its own, or can grow without limit (categories, authors, audit logs).

MongoDB documents have a 16 MB cap, so unbounded embedded arrays eventually break — another reason to reference large, growing collections.

Quick Check: Embed or Reference?

You are modeling an e-commerce backend with Beanie. A Product belongs to exactly one Category, categories are shared across thousands of products, and you frequently list all categories on their own admin page.

Recap: Document Modeling with Beanie

You learned how to model MongoDB data with Beanie on top of Pydantic:

  • Document subclasses map a Python class to a collection; class Settings sets the collection name and options.
  • init_beanie must run at startup (in FastAPI's lifespan) with your motor database and document_models.
  • Pydantic Field constraints and validators keep bad data out of the database.
  • Index with the Indexed wrapper for single fields or Settings.indexes + IndexModel for compound and unique indexes.
  • Embed owned, bounded, read-together data as nested BaseModels; reference shared or growing data with Link[...], mindful of the 16 MB document cap.

With these tools you can design typed, validated, query-efficient MongoDB schemas for your FastAPI backend.

Często zadawane pytania

Czy lekcja „Modelowanie dokumentów za pomocą Beanie ODM” jest bezpłatna?

Tak — pełny tekst „Modelowanie dokumentów za pomocą Beanie ODM” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu FastAPI Backend Development Bootcamp, przejdź na CoddyKit PRO. Kurs FastAPI Backend Development Bootcamp zawiera 4 lekcji w sumie.

Co nauczysz się w „Modelowanie dokumentów za pomocą Beanie ODM”?

Definiuj typowane modele dokumentów, indeksy i struktury osadzone za pomocą Beanie opartego na Pydantic. Ćwiczysz FastAPI Backend Development Bootcamp z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć FastAPI Backend Development Bootcamp?

Nie wymagamy żadnego doświadczenia. FastAPI Backend Development Bootcamp w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Modelowanie dokumentów za pomocą Beanie ODM”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji FastAPI Backend Development Bootcamp?

Tak. Każda lekcja FastAPI Backend Development Bootcamp zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Asynchroniczny dostęp do MongoDB za pomocą Motor
  2. Modelowanie dokumentów za pomocą Beanie ODM
  3. Potoki agregacji i złożone zapytania
  4. Ewolucja schematu i migracje dokumentów
← Powrót do FastAPI Backend Development Bootcamp