聚合管道在Python中必须用list包裹各阶段dict，字段名拼写、类型匹配（如ObjectId）、$group和$sum语法、参数安全构造是关键避错点。
聚合管道在Python中怎么写才不会报错
直接用 collection.aggregate() 就行，但常见错误是传入了非列表、用了错误的语法结构（比如把 pipeline 写成 dict 而不是 list），或者字段名拼错导致 $lookup 或 $group 失效。MongoDB 的聚合阶段必须按顺序放在一个 list 里，每个阶段是一个 dict；Python 中不能省略花括号或用等号代替冒号。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- pipeline 必须是
list类型，哪怕只有一个阶段也要写成[{"$match": {...}}] - 字段名带点号（如
"user.age"）时，$match里要用字符串，$project里可用嵌套字典或"$user.age"引用 - 避免在
$group的_id里混用表达式和字段名，比如{"$year": "$date"}和"$category"可以共存，但别漏掉引号 - 调试时先用 MongoDB Compass 或
mongosh验证 pipeline 逻辑，再复制到 Python
如何让 $lookup 关联另一张表并保留空结果
默认 $lookup 是左外连接，但如果你没看到关联文档，大概率是因为本地字段类型不匹配（比如一边是 ObjectId，另一边是字符串 ID），或者没加 $unwind 导致数组卡住。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 确保
localField和foreignField类型一致：用$toObjectId转换字符串 ID，例如{"$toObjectId": "$user_id"} - 如果想保留无匹配项的主文档，别加
$unwind；如果要展开数组字段再过滤，就加{"preserveNullAndEmptyArrays": True} - 关联后字段名默认叫
"orders"（你指定的as值），后续用"$orders.0.status"取第一个订单状态，但要注意空数组边界
分组统计时 count 和 sum 容易算错的原因
$sum: 1 才是计数，$sum: "$amount" 是求和；写成 $sum: "$count" 却没有该字段，就会返回 null——这在报表里表现为整列空白。
SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的 双功能合体技能 ，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途 ：；核心要点📝 题解模式 ：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式 ：输入 Python 代码，自动添加详细中。它将相关步骤、
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
$group的_id支持复合键：{"year": {"$year": "$created_at"}, "status": "$status"}，别漏掉外层大括号 - 计数统一用
{"count": {"$sum": 1}}，别用$count（那是聚合阶段，不是表达式操作符） - 需要去重计数？用
{"$addToSet": "$user_id"}+{"$size": "$users"}，而不是$sum配$cond - 注意时区：MongoDB 默认用 UTC，
$year/$month拿到的是 UTC 时间，报表日期可能偏移一天
Python里怎么安全地传参进聚合 pipeline
别用 f-string 拼接 pipeline，容易被注入（比如用户输入的 status 值含 "$ne": null 就会破坏结构）。MongoDB 驱动不支持参数化查询像 SQL 那样，得靠 Python 构造 dict。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用变量组装子句：
match_stage = {"status": status_filter} if status_filter else {}，再放进 pipeline list - 日期范围用
datetime对象，驱动会自动转为 BSON Date；别传字符串，否则$gte比较失效 - 动态字段名（如按不同维度分组）用
**{group_field: "$" + group_by}解包，但确保group_by是白名单内的字符串 - 大 pipeline 建议拆成函数生成，比如
build_date_range_match(start, end)，避免重复逻辑
聚合真正难的不是语法，而是理解每个阶段输出的数据结构——$group 后字段只剩 _id 和你显式定义的字段，之前的字段全丢了；$project 不加 _id: 0 就会默认带上，可能干扰后续排序。跑不通时，先加个 {"$limit": 5} 在中间阶段打印结果，比猜快得多。
