Asynchronous Python ODM for MongoDB
Project description
Getting Started with Beanie
Beanie - is an Asynchronous Python object-document mapper (ODM) for MongoDB, based on Motor and Pydantic.
When using Beanie each database collection has a corresponding Document
that
is used to interact with that collection. In addition to retrieving data,
Beanie allows you to add, update, or delete documents from the collection as
well.
Beanie saves you time by removing boiler-plate code and it helps you focus on the parts of your app that actually matter.
Data and schema migrations are supported by Beanie out of the box.
Installation
PIP
pip install beanie
Poetry
poetry add beanie
Basic Example
Document models
from typing import Optional
from pydantic import BaseModel
from beanie import Document, Indexed
class Category(BaseModel):
name: str
description: str
class Product(Document): # This is the model
name: str
description: Optional[str] = None
price: Indexed(float)
category: Category
class Collection:
name = "products"
Each document by default has id
ObjectId field, which reflects _id
MongoDB document field. It can be used later as an argument for the get()
method.
More details about Documents, collections, and indexes configuration could be found in the tutorial.
Initialization
import motor
from beanie import init_beanie
async def init():
# Crete Motor client
client = motor.motor_asyncio.AsyncIOMotorClient(
"mongodb://user:pass@host:27017"
)
# Init beanie with the Note document class
await init_beanie(database=client.db_name, document_models=[Product])
Create
chocolate = Category(name="Chocolate")
# Single:
bar = Product(name="Tony's", price=5.95, category=chocolate)
await bar.insert()
# Many
milka = Product(name="Milka", price=3.05, category=chocolate)
peanut_bar = Product(name="Peanut Bar", price=4.44, category=chocolate)
await Product.insert_many([milka, peanut_bar])
Other details and examples could be found in the tutorial
Find
# Single
# By id
bar = await Product.get("608da169eb9e17281f0ab2ff")
# By name
bar = await Product.find_one(Product.name == "Peanut Bar")
# Many
# By category
chocolates = await Product.find(
Product.category.name == "Chocolate"
).to_list()
# And by price
chocolates = await Product.find(
Product.category.name == "Chocolate",
Product.price < 5
).to_list()
# OR
chocolates = await Product.find(
Product.category.name == "Chocolate").find(
Product.price < 5).to_list()
# Complex example:
class ProductShortView(BaseModel):
name: str
price: float
products = await Product.find(
Product.category.name == "Chocolate",
Product.price < 3.5
).sort(-Product.price).limit(10).project(ProductShortView)
# All
all_products = await Product.all().to_list()
Information about sorting, skips, limits, and projections could be found in the tutorial
Update
# Single
await Product.find_one(Product.name == "Milka").set({Product.price: 3.33})
# Or
bar = await Product.find_one(Product.name == "Milka")
await bar.update(Set({Product.price: 3.33}))
# Or
bar.price = 3.33
await bar.replace()
# Many
await Product.find(
Product.category.name == "Chocolate"
).inc({Product.price: 1})
More details and examples about update queries could be found in the tutorial
Delete
# Single
await Product.find_one(Product.name == "Milka").delete()
# Or
bar = await Product.find_one(Product.name == "Milka")
await bar.delete()
# Many
await Product.find(
Product.category.name == "Chocolate"
).delete()
More information could be found in the tutorial
Aggregate
# With preset methods
avg_price = await Product.find(
Product.category.name == "Chocolate"
).avg(Product.price)
# Or without find query
avg_price = await Product.avg(Product.price)
# Native syntax
class OutputItem(BaseModel):
id: str = Field(None, alias="_id")
total: int
result = await Product.find(
Product.category.name == "Chocolate").aggregate(
[{"$group": {"_id": "$category.name", "total": {"$avg": "$price"}}}],
projection_model=OutputItem
).to_list()
Information about aggregation preset aggregation methods and native syntax aggregations could be found in the tutorial
Documentation
Example Projects
- FastAPI Demo - Beanie and FastAPI collaboration demonstration. CRUD and Aggregation.
- Indexes Demo - Regular and Geo Indexes usage example wrapped to a microservice.
Articles
- Announcing Beanie - MongoDB ODM
- Build a Cocktail API with Beanie and MongoDB
- MongoDB indexes with Beanie
- Beanie Projections. Reducing network and database load.
Resources
- GitHub - GitHub page of the project
- Changelog - list of all the valuable changes
- Discord - ask your questions, share ideas or just say
Hello!!
Supported by JetBrains
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.