Beanie: Python Objects as MongoDB Documents

Why it exists

Writing raw database queries in your application code is repetitive, error-prone, and tightly couples your logic to a specific database syntax. Object-Document Mappers (ODMs) were created to abstract away this boilerplate, allowing developers to work with familiar programming language objects and methods instead.

The mental model

Think of Beanie as a translator between your Python application and your MongoDB database. You define a contract for your data using a Pydantic class. Beanie then ensures that any data going into or out of the database conforms to that contract, translating your Python method calls (like Product.find_one()) into the appropriate MongoDB queries.

How it works

You define a class that inherits from beanie.Document. This class is also a Pydantic model, giving you automatic data validation and type hints. After initializing Beanie with your async MongoDB client and document models, you can use class methods to interact with the collection. For example, await my_product.insert() saves a new document, and await Product.find_one(Product.price < 10) retrieves one, all using async/await syntax.

When to use it

Use Beanie in async Python applications, especially with FastAPI, for standard CRUD (Create, Read, Update, Delete) operations. It excels at rapid development, providing type safety, editor autocompletion, and a clean, object-oriented way to manage data that maps cleanly to database documents.

When not to use it

For highly complex, performance-critical database operations, writing raw MongoDB Query Language (MQL) is often more efficient. Intricate aggregation pipelines or bulk data manipulations may be better handled without the ODM abstraction, which can obscure performance bottlenecks or lack the flexibility for fine-grained control.

One canonical example

First, you define a Product class inheriting from beanie.Document, with fields like name (a string) and price (a float). After initializing Beanie with your database client, you create an instance like new_product = Product(name="Mongo Mints", price=2.99). You save it to the database with a simple call: await new_product.insert(). To retrieve it, you use a class-level query: found_product = await Product.find_one(Product.price < 3.00). The result is a fully-formed Product object.