mongoengine 是 MongoDB 的 Python ODM (Object Document Mapper),提供類 Django ORM 的聲明式模型定義、查詢 API、驗證、信號等功能,讓 MongoDB 操作更 Pythonic。
pip install mongoengine pymongo
from mongoengine import connect
# 本地預設
connect('my_database')
# 遠端帶認證
connect('my_database', host='mongodb://user:pass@host:27017/db?authSource=admin')
# 多資料庫別名
connect('db1', alias='default')
connect('db2', alias='analytics')
from mongoengine import (
Document, EmbeddedDocument,
StringField, IntField, DateTimeField,
ListField, ReferenceField, EmbeddedDocumentField,
CASCADE, DENY
)
from datetime import datetime
class Category(Document):
name = StringField(max_length=50, required=True, unique=True)
article_count = IntField(default=0)
created_at = DateTimeField(default=datetime.utcnow)
meta = {
'collection': 'categories',
'indexes': ['name'],
'ordering': ['-created_at']
}
class Tag(EmbeddedDocument):
name = StringField(max_length=30, required=True)
created_at = DateTimeField(default=datetime.utcnow)
class Article(Document):
title = StringField(max_length=200, required=True)
content = StringField(required=True)
author = ReferenceField('User', reverse_delete_rule=CASCADE) # 刪除用戶時級聯刪除文章
tags = ListField(EmbeddedDocumentField(Tag))
category = ReferenceField(Category, reverse_delete_rule=DENY) # 禁止刪除有文章的分類
view_count = IntField(default=0)
published_at = DateTimeField(default=datetime.utcnow)
is_published = BooleanField(default=False)
meta = {
'collection': 'articles',
'indexes': [
'title',
'author',
'category',
'tags.name',
'-published_at',
{'fields': ['$title', '$content'], 'default_language': 'english'} # 文字索引
]
}
# 單筆
cat = Category(name="Python").save()
# 批次
Category.objects.insert([
Category(name="Django"),
Category(name="Flask"),
])
# 關聯文件
art = Article(
title="MongoEngine 入門",
content="...",
author=user_obj,
category=cat,
tags=[Tag(name="MongoDB"), Tag(name="ODM")]
).save()
# 全部
Article.objects.all()
# 過濾
Article.objects(title__icontains="mongo") # 模糊查詢
Article.objects(view_count__gte=100) # 比較運算符
Article.objects(tags__name="MongoDB") # 陣列嵌入欄位查詢
Article.objects(category=cat) # ReferenceField 查詢
Article.objects(category__name="Python") # 關聯欄位雙下底線查詢
# 切片/分頁
Article.objects.order_by('-published_at')[0:10] # 最新 10 筆
Article.objects.skip(20).limit(10) # 第 3 頁
# 僅選取欄位
Article.objects.only('title', 'published_at')
# 排除欄位
Article.objects.exclude('content')
# 聚合管線 (進階)
Article.objects.aggregate([
{"$group": {"_id": "$category", "count": {"$sum": 1}}},
{"$sort": {"count": -1}}
])
# 原子更新
Article.objects(id=art_id).update_one(inc__view_count=1) # 計數器 +1
Article.objects(id=art_id).update_one(set__title="新標題") # 設定欄位
Article.objects(is_published=False).update(set__is_published=True) # 批次更新
# 修改後儲存 (觸發驗證、信號)
art = Article.objects.get(id=art_id)
art.title = "新標題"
art.save()
Article.objects(id=art_id).delete() # 依條件刪除
art.delete() # 實例刪除
Category.objects(name="Test").delete() # 批次刪除
# 取得關聯物件 (自動解析)
art = Article.objects.first()
cat = art.category # 直接存取,自動查詢 Category
print(cat.name)
# 反向引用 (需在 ReferenceField 定義 reverse_delete_rule)
user = User.objects.first()
articles = user.article_set # 自動生成的反向查詢屬性
# 或自定義名稱: ReferenceField(User, reverse_delete_rule=CASCADE, reverse_delete_rule_name='articles')
資料儲存在父文件內部,無獨立集合,適合「屬於」關係 (如標籤、評論、地址)。
# 查詢嵌入文件
Article.objects(tags__name="Python") # 包含此標籤的文章
# 原子新增嵌入文件
Article.objects(id=art_id).update_one(push__tags=Tag(name="NewTag"))
# 原子移除嵌入文件
Article.objects(id=art_id).update_one(pull__tags__name="OldTag")
# settings.py
INSTALLED_APPS += ['mongoengine.django.mongo_auth']
# 使用 mongoengine 認證後端
AUTHENTICATION_BACKENDS = (
'mongoengine.django.auth.MongoEngineBackend',
)
# 在 views 中直接使用模型
from myapp.models import Article
def article_list(request):
articles = Article.objects(is_published=True).order_by('-published_at')[:10]
return render(request, 'list.html', {'articles': articles})
meta.indexes)。only()/exclude() 減少網路傳輸。insert() 而非循環 save()。select_related() (mongoengine 2.0+) 或手動批次獲取關聯。connect(..., maxPoolSize=100)。