聚合查询比普通find更易超时，因其串行执行全管道、内存处理、$lookup等阶段易触发全表扫描；需协同设置socketTimeoutMS（连接池）、maxTimeMS（服务端硬限）和allowDiskUse（防内存溢出）。
默认的 pymongo 连接超时和 socket 超时对聚合操作往往不够用，尤其当数据量大、管道阶段复杂（比如含 $lookup 或多层 $unwind）时，查询很容易触发 NetworkTimeout 或直接断连——这不是代码写错了，而是超时配置没跟上实际执行耗时。
聚合查询为什么比普通 find 更容易超时？
聚合操作在服务端是串行执行整个 pipeline，中间结果不落盘、全内存处理（除非显式启用 allowDiskUse=True），且某些阶段（如 $group、$lookup）可能触发全表扫描或远程集合访问。客户端等待的是“整个 pipeline 完成”，而非单个网络包响应，因此必须延长整体等待窗口。
-
find()超时通常只影响游标建立；而aggregate()默认会阻塞直到结果全部生成并开始返回 - 即使加了
cursor={}参数，pymongo仍会在首次调用next()或list()时触发完整执行+等待 - MongoDB 服务端的
maxTimeMS是硬限制，但客户端超时（socketTimeoutMS）可能先于它触发，导致报错不是ExecutionTimeout而是更模糊的NetworkTimeout
如何正确设置 pymongo 的超时参数？
关键不是只调大一个参数，而是分层控制：连接建立、网络读写、服务端执行三者要协同。直接改 socketTimeoutMS 到 30 秒可能掩盖问题，还拖慢失败感知。
- 连接池初始化时设
socketTimeoutMS=30000（30秒），避免单次读写卡死 - 聚合调用时显式传
maxTimeMS=25000（25秒），让服务端主动中断长任务，返回明确错误 - 禁用
connectTimeoutMS自动重试（即不设或设为None），否则聚合中途重连会丢失上下文 - 绝对不要在
aggregate()中混用timeout=True和自定义超时——这个布尔值只控制 cursor 创建，不作用于 pipeline 执行
示例：
result = collection.aggregate([
{"$match": {"status": "active"}},
{"$group": {"_id": "$category", "count": {"$sum": 1}}}
], maxTimeMS=25000, allowDiskUse=True)
什么时候必须加 allowDiskUse=True？
当聚合内存占用超过 100MB（MongoDB 默认限制），服务端会直接报 Exceeded memory limit 错误，此时超时设置再大也没用——它根本没走到超时那步，而是被内存策略拦截了。
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
立即学习“Python免费学习笔记（深入）”；
- 典型触发场景：
$group分组键太多、$lookup关联大集合、$unwind展开嵌套数组后数据膨胀 - 加
allowDiskUse=True后，MongoDB 会把中间结果暂存到/tmp目录，但注意磁盘空间和 IO 压力 - 该参数必须作为
aggregate()的顶层关键字参数传入，不能放在 pipeline 里 - 副本集环境下，临时文件只存在 primary 节点，不影响 secondary 同步逻辑
聚合慢但不超时？先查执行计划再调参
超时只是表象，根源常是低效 pipeline。别急着调 maxTimeMS，先用 explain("executionStats") 看真实瓶颈。
- 执行前加
explain=True参数（pymongo 4.0+），检查executionTimeMillis和totalDocsExamined - 如果
totalKeysExamined远小于totalDocsExamined，说明缺少索引——重点给$match阶段字段建复合索引 - 若
stage出现大量COLLSCAN，且发生在$lookup的 from 集合上，需在被关联集合的foreignField加索引 - 避免在
$match前放$project或$addFields——这会让过滤无法下推，白白处理更多文档
真正难搞的是跨分片聚合或带 JavaScript 表达式的 $redact，这些没法靠调超时解决，得重构逻辑或拆分查询。
