Aggregation Framework

What we're doing: Show a short real pipeline and trace what each stage contributes to the final shape.

db.orders.aggregate([
  { $match: { status: "delivered" } },
  { $group: { _id: "$customerId", total: { $sum: "$amount" } } },
  { $sort: { total: -1 } }
])

2

$match filters down to delivered orders only — the first stage narrows the working set before anything more expensive runs.

4

$group reshapes the documents entirely — the output is now one document per customer, not one per order, with a computed total.

Why this works: The pipeline shape (filter, then group, then sort) mirrors how a human would describe the task in words — "delivered orders, totaled per customer, biggest spenders first" — which is what makes aggregation pipelines readable despite doing real analytical work.

What we're doing: Use $replaceRoot and $facet to show two stages that reshape more dramatically than $project alone.

// $replaceRoot: promote a nested sub-document to be the whole output document
db.orders.aggregate([{ $replaceRoot: { newRoot: "$shippingAddress" } }])

// $facet: two independent summaries of the same input, in one round trip
db.orders.aggregate([{ $facet: {
  byStatus: [{ $group: { _id: "$status", count: { $sum: 1 } } }],
  byRegion: [{ $group: { _id: "$region", count: { $sum: 1 } } }]
} }])

2

$replaceRoot discards everything outside shippingAddress, making it the entire new document — a more drastic reshape than $project's field-by-field control.

5

$facet runs both sub-pipelines against the exact same input documents and returns both results together, avoiding two separate aggregate() calls.

Why this works: These two stages solve problems the simpler stages ($match, $project, $group alone) cannot — $replaceRoot for genuinely restructuring the document shape, $facet for needing multiple independent summaries without re-querying the collection multiple times.

What we're doing: Contrast two logically equivalent pipelines with very different real cost, based purely on stage order.

// Expensive: groups ALL orders first, then filters groups down to one region
db.orders.aggregate([
  { $group: { _id: "$region", total: { $sum: "$amount" } } },
  { $match: { _id: "west" } }
])

// Cheap: filters to one region's orders first, then groups only those
db.orders.aggregate([
  { $match: { region: "west" } },
  { $group: { _id: "$region", total: { $sum: "$amount" } } }
])

2

This pipeline computes a $sum for every region, across the entire collection, only to discard every result except one — most of that grouping work is wasted.

7

Filtering to the one relevant region first means $group only ever processes the documents that could contribute to the final answer.

Why this works: Both pipelines produce the identical final result — this is purely a cost difference, and it is the clearest possible illustration of why "logically correct" and "well-ordered" are different standards for a pipeline to meet.

What we're doing: Confirm with explain() that a leading $match uses an index, exactly the way find() does.

db.orders.createIndex({ status: 1 })

db.orders.aggregate([{ $match: { status: "pending" } }, { $group: {...} }]).explain()
// -> the $match stage's own explain shows "IXSCAN" on the status index — same mechanism as find({ status: "pending" })

1

This is the exact same index find() would use — an aggregation pipeline's leading $match is not a different mechanism, just a different call shape.

4

explain() on the aggregate() call shows the same stage-tree vocabulary (IXSCAN) as find()'s explain() — confirming the index really is used at this specific point in the pipeline.

Why this works: This equivalence — a leading $match using an index exactly like find() — is what makes "push $match early" a concrete, checkable optimization rather than a vague best practice: it is literally the difference between an indexed lookup and a full scan, verifiable the same way as any find() query.

What we're doing: Show a $group stage over a large collection needing disk spilling, and how to recognize that in explain()/execution stats.

db.events.aggregate([
  { $group: { _id: "$userId", eventCount: { $sum: 1 } } }
])
// -> on a large collection with millions of distinct userId values, the $group stage's
//    working set can exceed 100MB and spill to disk automatically (MongoDB 6.0+)

1

A $group with high-cardinality _id (many distinct userId values) has to hold a running total for every distinct value simultaneously — this is exactly the shape of workload that can exceed 100MB.

5

Automatic disk spilling means this query succeeds rather than erroring outright, but it runs slower than an equivalent group with a smaller working set — worth noticing, not just tolerating.

Why this works: Understanding which specific stages carry this risk (the ones that must hold state, not the ones that stream) is what lets someone predict, before running a pipeline, whether a given $group or $sort is a candidate for hitting the memory limit on a large enough collection.

What we're doing: Contrast fetching-and-looping against an equivalent aggregation for the same summary, quantifying the data-transfer difference.

// Application loop: fetch every delivered order, sum in code
const orders = await db.collection("orders").find({ status: "delivered" }).toArray()
const total = orders.reduce((sum, o) => sum + o.amount, 0)
// -> transfers every full order document just to compute one number

// Aggregation: the same result, computed where the data lives
const [{ total }] = await db.collection("orders").aggregate([
  { $match: { status: "delivered" } },
  { $group: { _id: null, total: { $sum: "$amount" } } }
]).toArray()

1

Every field of every delivered order crosses the network here, even though the application only ever uses the amount field, and only to add it up.

5

The aggregation computes the same single number without transferring any full document — only the final, tiny result crosses the network.

Why this works: This example makes the cost difference concrete: the application loop pays a network-transfer cost proportional to the full collection size, while the aggregation pays a cost proportional only to the final summary size — a gap that grows directly with how much the operation actually reduces the data.