$out and $merge for writing results in MongoDB - Step-by-Step Execution

Concept Flow - $out and $merge for writing results

Start Aggregation Pipeline

↓

Process Documents

↓

$out

↓

Replace Target

↓

Write Complete

↓

End

The pipeline processes documents, then either replaces a collection with $out or merges results into a collection with $merge.

Execution Sample

MongoDB

db.sales.aggregate([
  { $match: { status: "A" } },
  { $group: { _id: "$item", total: { $sum: "$amount" } } },
  { $merge: { into: "totals", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } }
])

This pipeline filters sales with status 'A', groups by item summing amounts, then merges results into 'totals' collection.

Execution Table

Step	Action	Documents Processed	Write Stage	Target Collection	Result
1	Match status 'A'	Filters documents with status 'A'	N/A	N/A	Filtered documents passed on
2	Group by item	Groups filtered docs by item, sums amounts	N/A	N/A	Grouped documents produced
3	Write with $merge	Uses grouped docs	$merge	totals	Documents merged into 'totals' collection
4	End	No more stages	N/A	N/A	Aggregation complete

💡 Pipeline ends after writing results with $merge to 'totals' collection

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3
Documents	All sales docs	Filtered docs with status 'A'	Grouped docs by item with totals	Written to 'totals' collection

Key Moments - 2 Insights

Why does $out replace the entire target collection but $merge can update or insert documents?

$out replaces the whole target collection with the pipeline output (see execution_table step 3 for $merge behavior). $merge allows more control by matching documents and updating or inserting them, preserving existing data not matched.

What happens if the target collection does not exist when using $merge?

If the target collection doesn't exist, $merge creates it automatically before inserting documents, as shown in execution_table step 3.

Visual Quiz - 3 Questions

Look at the execution_table at step 3, what write stage is used to update the 'totals' collection?

A $merge

B $out

C $group

D $match

💡 Hint

Check the 'Write Stage' column in execution_table row for step 3

According to variable_tracker, what is the state of 'Documents' after step 2?

A All sales documents

B Filtered docs with status 'A'

C Grouped docs by item with totals

D Written to 'totals' collection

💡 Hint

Look at the 'After Step 2' column for 'Documents' in variable_tracker

If we replace $merge with $out in the sample code, what would happen to the 'totals' collection?

A It would be merged with existing documents

B It would be replaced entirely by the pipeline output

C It would remain unchanged

D It would cause an error

💡 Hint

Recall the concept_flow difference between $out and $merge stages

Concept Snapshot

$out and $merge write pipeline results to collections.
$out replaces the entire target collection.
$merge updates or inserts documents based on matching keys.
Use $merge for incremental updates, $out for full replacement.
Both create target collection if missing.

Full Transcript

This visual execution shows how MongoDB aggregation pipelines can write results using $out or $merge stages. The pipeline starts by processing documents, such as filtering and grouping. Then, it chooses a write stage. The $out stage replaces the entire target collection with the pipeline output, effectively overwriting it. The $merge stage merges the pipeline output into the target collection by matching documents on specified keys, updating existing documents or inserting new ones. The execution table traces each step, showing document states and write actions. The variable tracker follows how documents change through the pipeline. Key moments clarify common confusions about $out replacing collections and $merge updating them. The quiz tests understanding of these behaviors referencing the execution visuals. The snapshot summarizes the key differences and usage of $out and $merge for writing aggregation results.