$out 是完全替换操作,会删除并重建目标集合,丢失索引、TTL、分片配置;必须位于管道末尾;分片集群中默认写入主分片且不继承分片键;增量更新应优先使用 $merge。

使用 $out 时必须注意集合是否已存在
$out 不是“追加”操作,而是完全替换目标集合。如果 myNewCollection 已存在,执行成功后原集合会被整个删除并重建——包括索引、TTL 设置、分片配置等全部丢失。这点和 $merge 有本质区别。
实操建议:
- 首次导出前,用
db.getCollectionNames().includes("myNewCollection")检查是否存在 - 若需保留旧数据或增量更新,改用
$merge(MongoDB 4.2+) - 生产环境务必在命令前加注释或做备份,例如先
db.myNewCollection.renameCollection("myNewCollection_backup_202405")
$out 必须是聚合管道的最后一个阶段
一旦写入 $out,后续阶段会被忽略,且无法再对输出结果做任何处理。MongoDB 会直接报错:"A pipeline stage cannot appear after the $out stage"。
常见错误场景:
- 误把
$out放在$project或$sort后面还想再加工 - 调试时临时加个
$limit测试,却放在$out之后
正确顺序示例:
db.orders.aggregate([
{ $match: { status: "completed" } },
{ $group: { _id: "$customerId", total: { $sum: "$amount" } } },
{ $sort: { total: -1 } },
{ $out: "customer_spend_summary" }
])
在分片集群中使用 $out 需要额外权限和限制
如果目标集合位于分片集群上,$out 会自动将结果写入主分片(primary shard),且新集合默认不继承源集合的分片键——也就是说,它会变成一个未分片集合,可能成为性能瓶颈。
关键约束:
- 执行用户需拥有
readWrite权限在目标数据库,以及moveChunk权限(若涉及跨分片写入) - 不能指定分片键;如需分片,导出后手动运行
sh.shardCollection("db.newColl", { shardKey: 1 }) - 不支持将结果直接写入另一个分片集群的远程数据库(
$out只作用于当前连接的集群)
替代方案:$merge 更适合多数实际需求
如果你真正想要的是“把聚合结果存到某集合,但不想丢掉已有数据”,$out 就不是合适选择。这时候 $merge 才是更可控的方案——它支持 on、whenMatched、whenNotMatched 等参数,能实现 upsert、保留字段、条件更新等行为。
比如只更新匹配用户的总消费,其余记录不动:
db.orders.aggregate([
{ $group: { _id: "$customerId", total: { $sum: "$amount" } } },
{
$merge: {
into: "customer_spend_summary",
on: "_id",
whenMatched: "replace",
whenNotMatched: "insert"
}
}
])
真正要用 $out 的场景其实很窄:确定要彻底覆盖、且不需要保留任何历史结构或元信息。其他时候,多花 30 秒换成 $merge 能避免半夜被报警叫醒。











