$replaceRoot（替换根文档）

最后更新：2026-10-09

$replaceRoot 用指定的内嵌文档替换整个文档，常用于把 detail 这类内嵌对象提升到顶层。替换后原文档的字段全部消失，只剩新根。若目标字段缺失或不是文档对象会报错；可先用 $ifNull 给默认值，或改用 $replaceWith 让结果为 null 时保留原文档。

📝 语法

{ $replaceRoot: { newRoot: <文档表达式> } }

newRoot	求值后作为新文档的表达式，必须是对象。

返回值：以 newRoot 为根的文档流

请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：

// $replaceRoot：把 detail 提升为根文档
db.orders.aggregate([
  { $replaceRoot: { newRoot: '$detail' } }
])

运行结果：

// 原订单字段消失，只剩 detail 的内容
{ "city": "SH", "zip": "200000" }

Q$replaceRoot 和 $project 有什么区别？

A$project 从原文档挑选或计算字段；$replaceRoot 用一个新的对象整体替换文档。

QnewRoot 指向的字段不存在会怎样？

A会报错。可先用 $ifNull 提供默认值，或用 $replaceWith 变体。

Q怎么把嵌套提升一层而不是全部替换？

A只提升部分层级可用 $project 的点号路径表达式；$replaceRoot 是整体替换根。

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。