$replaceRoot for restructuring in MongoDB - Step-by-Step Execution

Concept Flow - $replaceRoot for restructuring

Input Document

↓

$replaceRoot Stage

↓

New Root Document

↓

Output Document Stream

The $replaceRoot stage takes each input document and replaces its root with a specified embedded document, producing a new output document stream.

Execution Sample

MongoDB

db.collection.aggregate([
  { $replaceRoot: { newRoot: "$details" } }
])

This pipeline replaces each document's root with the embedded 'details' field.

Execution Table

Step	Input Document	Action	New Root Document	Output Document
1	{"_id":1, "name":"Alice", "details":{"age":30, "city":"NY"}}	Replace root with 'details' field	{"age":30, "city":"NY"}	{"age":30, "city":"NY"}
2	{"_id":2, "name":"Bob", "details":{"age":25, "city":"LA"}}	Replace root with 'details' field	{"age":25, "city":"LA"}	{"age":25, "city":"LA"}
3	{"_id":3, "name":"Carol", "details":{"age":27, "city":"SF"}}	Replace root with 'details' field	{"age":27, "city":"SF"}	{"age":27, "city":"SF"}
4	No more documents	End of pipeline	N/A	N/A

💡 All input documents processed; pipeline ends.

Variable Tracker

Variable	Start	After 1	After 2	After 3	Final
Current Document	{"_id":1, "name":"Alice", "details":{"age":30, "city":"NY"}}	{"_id":2, "name":"Bob", "details":{"age":25, "city":"LA"}}	{"_id":3, "name":"Carol", "details":{"age":27, "city":"SF"}}	No more documents	N/A
Root Document	Same as Current Document	{"age":30, "city":"NY"}	{"age":25, "city":"LA"}	{"age":27, "city":"SF"}	N/A

Key Moments - 2 Insights

Why does the output document no longer have the original _id or name fields?

Because $replaceRoot replaces the entire root with the specified embedded document (here 'details'), the original fields like _id and name are removed. See execution_table rows 1-3 where output only has 'age' and 'city'.

What happens if the specified newRoot field does not exist in a document?

If the newRoot field is missing, the pipeline will error. This example assumes 'details' exists in every document, as shown in execution_table rows 1-3.

Visual Quiz - 3 Questions

Look at the execution table at step 2, what is the output document?

A {"details":{"age":25, "city":"LA"}}

B {"_id":2, "name":"Bob"}

C {"age":25, "city":"LA"}

D {"age":30, "city":"NY"}

💡 Hint

Check the 'Output Document' column at step 2 in the execution_table.

At which step does the pipeline finish processing all documents?

A Step 3

B Step 4

C Step 1

D Step 2

💡 Hint

Look for the row where 'No more documents' appears in the 'Input Document' column.

If the newRoot was set to {name: "$name"} instead of "$details", what would the output document at step 1 be?

A {"name":"Alice"}

B "Alice"

C {"_id":1, "name":"Alice"}

D {"details":{"age":30, "city":"NY"}}

💡 Hint

Replacing root with {name: "$name"} results in {"name":"Alice"}.

Concept Snapshot

$replaceRoot stage replaces the entire document root with a specified embedded document.
Syntax: { $replaceRoot: { newRoot: <expression> } }
Commonly used to flatten nested documents.
Output documents lose original root fields unless included in newRoot.
Errors if newRoot field is missing.

Full Transcript

The $replaceRoot stage in MongoDB aggregation takes each input document and replaces its root with a specified embedded document. For example, if documents have a 'details' field with nested info, $replaceRoot can make 'details' the new root, removing other fields like _id or name. The execution table shows step-by-step how each document is transformed. Beginners often wonder why original fields disappear; it's because the entire root is replaced. Also, if the newRoot field is missing, the pipeline can error. This visual trace helps understand how $replaceRoot restructures documents in a pipeline.