MongoDB Aggregation Pipeline

Aggregation processes documents through a series of steps — a pipeline — and returns computed results, like totals, averages, groupings, and reshaped documents. It's how MongoDB answers questions that a plain find() query can't: "what's the total fare per passenger class?", "how many employees are in each city?", and so on.

Basic Syntax

db.collection.aggregate([ {stage1}, {stage2}, {stage3}, ... ])

Each stage takes the output of the previous stage as its input — documents flow through the pipeline like water through pipes, being filtered, grouped, or reshaped at each step.

A Visual Example

db.train.aggregate([
  { $match: { class: "first-class" } },
  { $group: { _id: "$id", total: { $sum: "$fare" } } }
])

1. $match filters down to only first-class documents (just like a find() query).
2. $group then groups the survivors by passenger id and sums their fare into total.

Stages, Expressions & Accumulators

db.train.aggregate([{ $group: { _id: "$id", total: { $sum: "$fare" } } }])
//                     ↑ stage         ↑ expression    ↑ accumulator

• A stage (like $match, $group, $sort) is one step in the pipeline.
• An expression (like "$id" or "$fare") refers to a field's value from the input documents.
• An accumulator (like $sum) combines values across a group of documents into one result.

Common Pipeline Stages

Stage	Description
$match	Filters documents — similar to find()
$project	Selects specific fields to keep
$group	Groups documents by a value and computes aggregates
$sort	Reorders documents
$skip	Skips the first n documents
$limit	Limits to the first n documents
$unwind	Deconstructs an array field into one document per element
$out	Writes the final results into a new collection

Notes

• In $group, the _id field is mandatory — it's what defines each group.
• $out must always be the last stage in the pipeline.

Common Errors & Troubleshooting

• Unrecognized pipeline stage name — a common typo culprit: stage names always start with $ ($match, not match). Also double-check spelling — MongoDB won't autocorrect a misspelled stage name.
• $out isn't the last stage → error — $out (and its newer cousin $merge) must always be the final stage in the pipeline; putting anything after it throws an error.
• Forgetting _id is required in $group — leaving out _id entirely in a $group stage causes a syntax error; use _id: null explicitly if you want to group the whole collection into one bucket.

Key Takeaways

• The aggregation pipeline is a sequence of stages, each transforming the documents that flow through it.
• $match + $group is the most common pair: filter first, then summarize.
• _id in $group is required — it's the grouping key, not the document's original _id.