$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.

Practice

1. What does the $replaceRoot stage do in a MongoDB aggregation pipeline?

easy

A. It groups documents by a specified key.

B. It filters documents based on a condition.

C. It replaces the entire document with the specified embedded document.

D. It sorts documents by a specified field.

Solution

1. Step 1: Understand the purpose of $replaceRoot

   $replaceRoot replaces the whole document with a specified nested document inside it.

2. Step 2: Compare with other stages

   Filtering, sorting, and grouping are done by $match, $sort, and $group respectively, not $replaceRoot.

3. Final Answer:

   It replaces the entire document with the specified embedded document. -> Option C

4. Quick Check:

   $replaceRoot changes document root [OK]

Hint: Remember: $replaceRoot swaps the whole document root [OK]

Common Mistakes:

• Confusing $replaceRoot with filtering or sorting stages
• Thinking it only modifies part of the document
• Assuming it adds fields instead of replacing

2. Which of the following is the correct syntax to use $replaceRoot to replace the root with the details field?

easy

A. { $replaceRoot: { newRoot: "$details" } }

B. { $replaceRoot: { root: "$details" } }

C. { $replaceRoot: { newRoot: details } }

D. { $replaceRoot: { newRoot: "$details" }, $match: {} }

Solution

1. Step 1: Recall correct $replaceRoot syntax

   The correct syntax requires newRoot with a string path starting with "$" to specify the field.

2. Step 2: Analyze options

   { $replaceRoot: { newRoot: "$details" } } uses newRoot: "$details" which is correct. { $replaceRoot: { root: "$details" } } uses wrong key root. { $replaceRoot: { newRoot: details } } misses quotes around field path. { $replaceRoot: { newRoot: "$details" }, $match: {} } adds an unrelated $match inside the same stage, which is invalid.

3. Final Answer:

   { $replaceRoot: { newRoot: "$details" } } -> Option A

4. Quick Check:

   Use newRoot: "$field" syntax [OK]

Hint: Use newRoot: "$fieldName" exactly [OK]

Common Mistakes:

• Omitting quotes around field path
• Using wrong key like 'root' instead of 'newRoot'
• Combining stages incorrectly

3. Given the collection documents:

{ "name": "Alice", "info": { "age": 30, "city": "NY" } }

What will be the output of this aggregation?

[{ $replaceRoot: { newRoot: "$info" } }]

medium

A. [{ "name": "Alice", "info": { "age": 30, "city": "NY" } }]

B. [{ "age": 30, "city": "NY" }]

C. [{ "info": { "age": 30, "city": "NY" } }]

D. [{ "age": 30 }]

Solution

1. Step 1: Understand $replaceRoot effect

   The stage replaces the whole document with the content of the info field.

2. Step 2: Apply to given document

   Original document has info as { "age": 30, "city": "NY" }, so output document is exactly that object.

3. Final Answer:

   [{ "age": 30, "city": "NY" }] -> Option B

4. Quick Check:

   Root replaced by info field content [OK]

Hint: Output matches the nested field content exactly [OK]

Common Mistakes:

• Expecting original fields to remain
• Confusing nested field with root
• Selecting wrong output format

4. You wrote this aggregation but it throws an error:

[{ $replaceRoot: { newRoot: info } }]

What is the error and how to fix it?

medium

A. Missing quotes around field path; fix with newRoot: "$info".

B. Wrong operator; use $setRoot instead of $replaceRoot.

C. Field info does not exist; add it first.

D. Aggregation pipeline must be an object, not an array.

Solution

1. Step 1: Identify syntax error in newRoot value

   The field path must be a string starting with "$" to indicate a field reference.

2. Step 2: Correct the syntax

   Change newRoot: info to newRoot: "$info" to fix the error.

3. Final Answer:

   Missing quotes around field path; fix with newRoot: "$info". -> Option A

4. Quick Check:

   Field paths need quotes and $ prefix [OK]

Hint: Always quote field paths with $ prefix [OK]

Common Mistakes:

• Omitting quotes around field names
• Confusing $replaceRoot with $setRoot
• Misunderstanding pipeline array structure

5. You have documents:

{ "user": { "id": 1, "name": "Bob" }, "score": 50 }

How do you write an aggregation pipeline using $replaceRoot to make the output documents only contain the user fields plus the score field at the root level?

hard

A. [{ $replaceRoot: { newRoot: "$score" } }]

B. [{ $replaceRoot: { newRoot: "$user" } }, { $addFields: { score: "$score" } }]

C. [{ $project: { user: 1, score: 1 } }]

D. [{ $replaceRoot: { newRoot: { $mergeObjects: ["$user", { score: "$score" }] } } }]

Solution

1. Step 1: Understand the goal

   We want to flatten user fields to root and keep score alongside.

2. Step 2: Use $mergeObjects inside $replaceRoot

   $mergeObjects combines user object and { score: "$score" } into one root document.

3. Step 3: Check options

   [{ $replaceRoot: { newRoot: { $mergeObjects: ["$user", { score: "$score" }] } } }] correctly merges and replaces root. [{ $replaceRoot: { newRoot: "$user" } }, { $addFields: { score: "$score" } }] tries to add fields after replacing root, but score is lost after first stage. [{ $project: { user: 1, score: 1 } }] only projects fields, not restructuring. [{ $replaceRoot: { newRoot: "$score" } }] replaces root with score only, losing user.

4. Final Answer:

   [{ $replaceRoot: { newRoot: { $mergeObjects: ["$user", { score: "$score" }] } } }] -> Option D

5. Quick Check:

   Use $mergeObjects to combine fields [OK]

Hint: Combine objects with $mergeObjects inside $replaceRoot [OK]

Common Mistakes:

• Replacing root with only one field losing others
• Trying to add fields after $replaceRoot without preserving data
• Using $project instead of restructuring