MongoDB的聚合管道是数据处理的核心能力，从简单的分组统计到复杂的多阶段转换都离不开它。但很多使用者在面对大数据量聚合结果时，会遇到内存告警、查询中途断开、游标超时等问题，这些问题的根源往往与游标的行为密切相关。理解聚合管道的游标机制，掌握游标信息的读取和调优方法，对写出稳定高效的聚合查询非常重要。
聚合管道的游标返回结构是什么
从MongoDB 2.6版本开始，aggregate命令的返回结果就统一改成了游标形式。即使你在mongosh里执行一条简单的聚合语句，底层返回的也是一个包含游标描述的文档，而不是一次性把所有结果塞进内存。这个设计对大结果集非常友好，服务端可以分批推送数据，客户端按需拉取。
执行aggregate命令后，返回文档中会包含一个cursor字段，它的典型结构如下：
{
"cursor" : {
"firstBatch" : [ ],
"id" : NumberLong("8168234567891234567"),
"ns" : "testdb.orders"
},
"ok" : 1
}
其中firstBatch是第一批文档，id是服务端维护的游标编号，ns是命名空间。这里有一个关键点：如果id为0，说明结果已经全部返回，游标立即关闭；如果id不为0，说明还有剩余数据，客户端需要拿着这个ID调用getMore继续拉取。判断游标是否耗尽，就是看这个ID是否归零。
你可以用explain来观察聚合管道的执行细节，其中也包含游标相关的信息：
db.orders.explain("executionStats").aggregate([
{ $match: { status: "paid" } },
{ $group: { _id: "$city", total: { $sum: "$amount" } } }
]);
explain结果中的executionStats会展示nReturned、executionTimeMillis等指标，配合游标的批次行为一起分析，可以判断聚合是不是被某个阶段拖慢了。
batchSize参数如何影响性能与内存
aggregate命令支持一个cursor选项，里面可以指定batchSize，它控制服务端每批返回的文档数量。默认情况下第一批最多返回101个文档，后续批次最多16MB（这是BSON文档传输的最大限制）。很多内存问题其实就出在对这个参数的误解上。
来看一个显式指定batchSize的例子：
// mongosh中通过aggregate的options传入
db.orders.aggregate(
[
{ $match: { status: "paid" } },
{ $sort: { createdAt: -1 } },
{ $project: { city: 1, amount: 1 } }
],
{ cursor: { batchSize: 500 } }
);
如果把batchSize设置得过大，比如几十万，服务端一次性打包推送的数据量会非常庞大，客户端驱动需要分配大块内存来接收，网络传输时间也会拉长，容易触发驱动的超时设置。反过来，batchSize太小又会导致getMore往返次数过多，往返延迟会累积成明显的性能损耗。一般建议根据单条文档的大小来估算，让每批数据控制在几百KB到几MB之间比较稳妥。
还有一个容易混淆的概念：聚合阶段里的$limit和游标的batchSize是完全不同的东西。$limit是在管道层面限制最终结果数量，而batchSize只影响每次网络传输多少条，不影响总结果集大小。不少初学者以为设置了batchSize就等于限制了返回总量，结果线上查询拉回了海量数据，这是需要特别避开的坑。
游标生命周期管理与常见问题排查
游标从创建到销毁有自己的生命周期。服务端默认给空闲游标设置了10分钟的超时时间（由参数cursorTimeoutMillis控制），超时后游标会被自动回收。但如果客户端设置了noCursorTimeout选项，游标就不会自动过期，此时如果应用异常退出而没有显式关闭游标，就会造成游标泄漏，堆积多了会占用服务端内存甚至触发连接数上限。
排查游标状态可以用serverStatus命令查看当前打开的游标统计：
db.serverStatus().metrics.cursor;
// 输出示例
{
"moreThanOneBatch" : NumberLong(12),
"timedOut" : NumberLong(3),
"totalOpened" : NumberLong(1520),
"lifespan" : {
"1 second or less" : NumberLong(1400),
"1 minute or less" : NumberLong(90),
"greater than 10 minutes" : NumberLong(2)
},
"open" : {
"noTimeout" : NumberLong(0),
"pinned" : NumberLong(1),
"multiTarget" : NumberLong(0),
"singleTarget" : NumberLong(1),
"total" : NumberLong(1)
}
}
这里面最需要关注的是open.noTimeout和open.total。如果noTimeout的数量持续增长，基本可以断定应用里有设置了noCursorTimeout的游标没有被关闭，需要检查代码中是否缺少了cursor.close()调用。timedOut则反映了有多少游标因超时被服务端强制回收，如果这个数字很高，说明客户端处理一批数据的时间经常超过10分钟，要么增大batchSize减少等待，要么调整cursorTimeoutMillis。
另一个实用命令是$currentOp配合游标过滤，可以定位当前正在执行的聚合操作和它关联的游标：
db.aggregate([
{ $currentOp: { allUsers: true } },
{ $match: { type: "op", "cursor.id": { $exists: true } } },
{ $project: { opid: 1, ns: 1, command: 1, secs_running: 1, "cursor": 1 } }
]);
对于确认已经泄漏的游标，可以通过killCursors命令手动清理：
db.runCommand({
killCursors: "orders",
cursors: [ NumberLong("8168234567891234567") ]
});
在日常开发中，建议养成几个习惯：驱动层面尽量使用迭代器方式遍历聚合结果，而不是先toArray再处理，这样能边拉取边消费，内存更平稳；对长时间后台任务使用noCursorTimeout时，务必用try-finally保证游标关闭；写入压力大的集合上做长聚合时，注意聚合操作读到的是快照数据的一致性问题，必要时在业务层做校验。
总结
聚合管道的游标机制看似只是返回格式的一个细节，实际上串起了内存控制、网络传输和服务端资源管理。理解cursor字段中id与firstBatch的含义，合理设置batchSize，监控serverStatus中的游标指标并及时清理泄漏游标，这几件事做到位，大部分与聚合相关的超时和内存问题都能提前规避。把它当作调优聚合查询的基本功来练习，比出问题后再临时排查要省心得多。
MongoDB聚合管道游标信息cursorInfo修改时间：2026-09-14 03:58:42