$merge（合并写入）
最后更新：2026-10-09
$merge（合并写入）
$merge 把管道结果写入目标集合（可跨库、跨集群），支持按匹配键更新已有文档或插入新文档，是 $out 的增强版。它必须是管道最后一个阶段。核心选项：into 目标、on 匹配字段、whenMatched 与 whenNotMatched 控制重复键处理。适合 ETL 落库、物化视图、跨集合同步。
| 分类 | 高级与诊断 |
|---|---|
| MongoDB 版本 | 4.2+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $merge: { into: "<集合名>", on: "<匹配字段>", whenMatched: "merge", whenNotMatched: "insert" } }⚙️ 参数
| into | 目标集合，可为字符串或 { db, coll } 对象。 |
|---|---|
| on | 匹配已有文档的字段，默认 _id。 |
| whenMatched | 匹配到时的行为：merge、replace、keepExisting 或自定义管道。 |
| whenNotMatched | 未匹配到时的行为：insert 或 discard。 |
返回值：不向后续阶段输出文档（结果写入目标集合）
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $merge：把客户汇总写入 cust_stats
db.orders.aggregate([
{ $group: { _id: '$cust_id', total: { $sum: '$amount' } } },
{ $merge: {
into: 'cust_stats',
on: '_id',
whenMatched: 'replace',
whenNotMatched: 'insert'
} }
])运行结果：
// cust_stats 集合被更新/插入📌 注意事项
- 必须是管道最后一个阶段
- into 为字符串时目标集合不存在会自动创建
- 默认 whenMatched 为 merge、whenNotMatched 为 insert
🏷️ 相关标签
💡 相关案例
📚 相关教程
❓ 常见问题
Q$merge 和 $out 有什么区别？
A$out 整集合替换；$merge 支持按键更新、增量写入和跨库目标。
Q能写入另一个数据库吗？
A能，into 可写成 'db.coll' 形式或 { db, coll } 对象。
Q重复键怎么处理？
AwhenMatched 控制：merge 合并字段、replace 整文档替换、keepExisting 保留原文档。
