Beanie ODM Documentation

Lazy parsing allows you to skip the upfront parsing and validation process for documents. Instead, validation is performed on demand for each field individually when it is accessed. This can improve performance by reducing initial processing overhead, though it may introduce slight overhead during field access later.

await Sample.find(Sample.number == 10, lazy_parse=True).to_list()

You can delete a single document in Beanie using two methods:

1. Directly from a query: Use find_one() with a filter and call .delete() on the resulting object.
2. From an existing instance: If you already have a document instance, call .delete() directly on that instance.

Both methods are asynchronous and must be awaited.

# Method 1: Delete directly from a query
await Product.find_one(Product.name == "Milka").delete()

# Method 2: Delete an existing instance
bar = await Product.find_one(Product.name == "Milka")
await bar.delete()

To run tests or use Beanie during development, you need an accessible MongoDB database.

• Standard usage/tests: Assume a local database hosted on port 27017 without authentication.
• Migrations: Requires a connection to a Replica Set or a Mongos instance.

To map and handle data from a MongoDB collection, inherit from the Document class. Since Document inherits from Pydantic's BaseModel, it supports standard Pydantic data typing and parsing. You can use an inner Settings class to configure collection-specific metadata like names and indexes.

from typing import Optional
import pymongo
from pydantic import BaseModel
from beanie import Document, Indexed

class Category(BaseModel):
    name: str
    description: str

class Product(Document):
    name: str
    description: Optional[str] = None
    price: Indexed(float, pymongo.DESCENDING)
    category: Category

    class Settings:
        name = "products"
        indexes = [
            [
                ("name", pymongo.TEXT),
                ("description", pymongo.TEXT),
            ],
        ]

To use the Task Queue features in Beanie, install the queue extra via pip.

pip install beanie[queue]

Beanie documentation is generated using pydoc-markdown (which uses mkdocs internally). To preview your documentation edits locally, run the pydoc-markdown server and visit the provided address (typically http://localhost:8000).

Note: API documentation is automatically generated from source docstrings, while other documentation is written manually.

pydoc-markdown --server

To remove documents from the database, call the .delete() method on a found document or on a query result.

# Delete a specific document instance
bar = await Product.find_one(Product.name == "Milka")
await bar.delete()

# Delete via query
await Product.find_one(Product.name == "Milka").delete()
await Product.find(Product.category.name == "Chocolate").delete()

To prepare a new version of Beanie, you must create a Pull Request that updates the versioning across multiple files and generates an updated changelog.

1. Update pyproject.toml: Change the version field to the new version number.
2. Update beanie/__init__.py: Change the __version__ variable to the new version number.
3. Update Changelog:
   • Edit scripts/generate_changelog.py to set current_version and new_version.
   • Run the generation script (see 'Generate the changelog' below).
   • Copy the output into the top of docs/changelog.md.
4. Submit PR: Create a PR with a descriptive title and ensure all CI checks pass.

Use the .upsert() method to insert a document if no documents match the search criteria. When using upsert, you can provide an on_insert parameter to define the document to be created if the update results in an insertion.

await Product.find_one(Product.name == "Tony's").upsert(
    Set({Product.price: 3.33}), 
    on_insert=Product(name="Tony's", price=3.33, category=chocolate)
)

Beanie provides high-level helper methods for common aggregation tasks like calculating averages. You can run these aggregations on a filtered subset of documents using .find() or over the entire collection by calling the method directly on the Document class.

# With a search (filtered subset):
avg_price = await Product.find(
    Product.category.name == "Chocolate"
).avg(Product.price)

# Over the whole collection:
avg_price = await Product.avg(Product.price)