MongoDB $replaceRoot Stage

What Is $replaceRoot?

$replaceRoot is a MongoDB aggregation stage that replaces the whole input document with newRoot. Use it to promote an embedded document to the top level, or to emit a newly built document shape.

$replaceRoot = swap the whole document

{ $replaceRoot: { newRoot: <document expression> } }

newRoot must resolve to a document
(missing / non-document → error)

Common:
  newRoot: "$name"              // promote nested object
  newRoot: { full: ... }        // build a new object

vs $replaceWith → same job, shorter form
vs $project     → reshape fields vs replace entire root

How to Use $replaceRoot in MongoDB

Choose what becomes the new document, ensure it is always a document, then place the stage in the pipeline.

1. Decide the new root—a field path like "$name", or a built object.
2. Optional: $match so every document has that nested field.
3. Add { $replaceRoot: { newRoot: <expression> } }.
4. If you still need _id or defaults, merge with $mergeObjects or guard with $ifNull.

Pseudocode

for each document:
    next = evaluate(newRoot)
    if next is missing or not a document:
        error
    emit next   // old fields (including _id) are gone

Cheat Sheet

Keep these facts handy while promoting documents.

Live Preview

Pick a newRoot style and see how one person document changes.

$replaceRoot: { newRoot: "$name" }

output:
  { first: "Grace", last: "Hopper" }

Worked Walkthrough — Promote Nested Name

A person document wraps first / last inside name. Goal: make that nested object the whole document.

Document in:
  { _id: 1, name: { first: "Grace", last: "Hopper" }, city: "NY" }

$replaceRoot:
  newRoot: "$name"

Document out:
  { first: "Grace", last: "Hopper" }

Note: _id and city are gone unless you merge them into newRoot

MongoDB Examples

Insert sample people, promote a nested name, then build a new root. Run these in mongosh in order.

db.people.insertMany([
  {
    _id: 1,
    name: { first: "Grace", last: "Hopper" },
    city: "NY"
  },
  {
    _id: 2,
    name: { first: "Alan", last: "Turing" },
    city: "London"
  }
]);

db.people.find()

[
  {
    _id: 1,
    name: { first: "Grace", last: "Hopper" },
    city: "NY"
  },
  {
    _id: 2,
    name: { first: "Alan", last: "Turing" },
    city: "London"
  }
]

db.people.aggregate([
  {
    $replaceRoot: {
      newRoot: "$name"
    }
  }
]);

[
  { first: "Grace", last: "Hopper" },
  { first: "Alan", last: "Turing" }
]

db.people.aggregate([
  {
    $replaceRoot: {
      newRoot: {
        _id: "$_id",
        full_name: {
          $concat: ["$name.first", " ", "$name.last"]
        }
      }
    }
  }
]);

[
  { _id: 1, full_name: "Grace Hopper" },
  { _id: 2, full_name: "Alan Turing" }
]

Performance Notes

Prefer $match before $replaceRoot when some documents lack the nested field. Pairing with $unwind multiplies documents—use it only when you need that shape.

Key Takeaways