Python如何使用Motor实现MongoDB的流式数据读取_使用async for遍历游标
作者：袖梨
2026-07-03
Motor游标默认支持async for遍历，但需避免提前await游标、调用to_list()等导致游标耗尽；应直接赋值cursor = collection.find(...)后async for遍历，并注意超时、索引、生命周期等服务端约束。
Motor游标默认不支持async for直接遍历？
Motor 3.0+ 版本中，find() 返回的 AsyncIOMotorCursor 确实支持 async for，但前提是：你没调用过 to_list()、next() 或提前 await 了游标本身。常见错误是误以为“返回游标就得先 await”，结果写成 cursor = await collection.find(...) —— 这会立刻触发查询并把整个游标对象变成一个不可再迭代的“已消耗”状态，后续 async for doc in cursor 就会报 RuntimeError: async generator already exhausted。
- 正确做法：直接
cursor = collection.find(...)（不 await），再async for doc in cursor - 若需限制数量，用
.limit(n)，别用to_list(n)，后者会一次性拉取全部到内存 - 游标生命周期绑定到当前 asyncio task；task 被 cancel 时，Motor 会自动清理未完成的网络请求
如何避免游标超时或连接中断导致遍历失败？
MongoDB 默认游标超时时间为 10 分钟（maxTimeMS 不影响这个），一旦空闲超过阈值，服务端会销毁游标，再次 async for 就会抛 ExecutionTimeout 或 InvalidOperation: cursor does not exist。这不是 Motor 的 bug，而是 MongoDB 的设计。
- 对长耗时流式处理，显式禁用超时：
collection.find(..., no_cursor_timeout=True) - 更稳妥的做法是配合
max_await_time_ms（仅适用于 tailable cursor）或业务层心跳：每处理 N 条就await asyncio.sleep(0)让出控制权，避免 event loop 长时间阻塞 - 不要在
async for循环里做同步阻塞操作（如time.sleep、文件读写），否则游标空闲时间会被拉长
async for 遍历时能否中途修改查询条件或跳过数据？
不能。MongoDB 游标是前向只读的，Motor 的 AsyncIOMotorCursor 不提供 skip()、rewind() 或动态改 filter 的能力。所谓“跳过前 N 条”，必须在执行 find() 前通过 .skip(N) 设置；“按条件中断”只能靠 Python 层 break，不会通知 MongoDB 提前终止游标。
- 如果需要分页式流式消费，用
_id范围查询替代skip()：记录上一批最后的doc['_id']，下一次查{'_id': {'$gt': last_id}} - 想实现“消费到某时间戳就停”，把时间字段加到
sort和filter中，而不是依赖循环内判断 -
async for每次迭代实际发起一次getMore请求（batch size 默认 101），不是真的一条一条发网络包
为什么有时 async for 看起来“卡住”没输出？
最常见原因是：查询没命中索引，MongoDB 执行全表扫描，而 Motor 在等待第一批 batch 返回。此时 async for 会挂起，直到服务端返回首个结果块，期间没有任何日志或 timeout 提示。
立即学习“Python免费学习笔记（深入）”；
- 用
explain()检查执行计划：await collection.find({...}).explain()，确认executionStats.nReturned > 0且stage是IXSCAN而非COLLSCAN - 确保
sort()字段有对应索引，否则游标无法高效推进（尤其带limit()时） - 调试阶段可在循环内加
print(f"got {doc.get('_id')}")，但生产环境避免高频 print，它可能成为性能瓶颈
