What does explain() on an aggregation pipeline show that the pipeline text does not?

## Asking for it Two equivalent forms exist: ```javascript db.orders.explain("executionStats").aggregate(pipeline) db.orders.aggregate(pipeline, { explain: true }) ``` The verbosity argument follows the usual ladder — plan-only, plan plus execution counters, or all considered plans. Plan-only tells you what the server intends to do; execution statistics tell you what it actually did, which is what you want when a pipeline is slow rather than merely suspicious. ## The stages array is the optimized pipeline The most under-used fact about aggregation explain output is that the `stages` array is not your pipeline — it is the pipeline the optimizer produced. Every rewrite is visible there: - a `$match` that has moved ahead of a `$project`, `$addFields` or `$sort`; - two `$match` stages merged into a single predicate; - consecutive `$limit` or `$skip` stages collapsed; - a `$limit` absorbed into the preceding `$sort`, so the sort retains only the top *n*. This converts "I think MongoDB pushes filters down" into an observation. If your `$match` is still sitting where you wrote it, the optimizer could not move it — usually because the predicate touches a field a preceding stage computed — and you now know it is your job to restructure the pipeline. ## The $cursor stage is the boundary When a pipeline starts by reading a collection, the leading element of `stages` is a `$cursor` stage. It contains a `queryPlanner` section — and, under `executionStats`, the execution counters — for the query the aggregation framework handed to the ordinary query layer. That stage is conceptually the seam of the whole system. Everything inside `$cursor` is normal query execution: a predicate, possibly a projection, an index scan or a collection scan. Everything after it is aggregation-layer work over a stream of documents, where no index can help. When someone asks "did my pipeline use the index?", the honest answer is "look inside `$cursor`" — and the corollary is that if the filter you care about is *not* inside `$cursor`, it never had a chance to. The counters inside that stage are read the same way as for any query, which is the ordinary query-plan skill; the pipeline-specific insight is which part of your pipeline made it in there at all. ## Sharded pipelines Against a sharded collection the shape changes. The output describes how the pipeline was divided: a portion executed on each shard, and a merging portion executed on the router or a designated shard, with a section naming which stages went where. This is how you discover that a stage you assumed ran in parallel is actually running once on the merging node over everything the shards sent back — a common cause of a pipeline that scales badly as shards are added. ## Other things worth noticing Recent server versions report an `explainVersion` field, because the newer execution engine produces a different plan representation; do not be alarmed when the plan tree looks unfamiliar between versions, and compare like with like when you keep before/after plans. ## What explain does not tell you It does not tell you whether the pipeline is *correct*, and it does not report business meaning. It also does not by itself tell you whether a blocking stage will spill on tomorrow's data volume — you infer that from how many documents reach the stage and how many distinct groups it builds. And a plan captured on a small development dataset can differ from production, because the choice among candidate plans depends on the data. ## Using it well The habit that pays: capture explain output before a change and after it, and compare the optimized `stages` array and the `$cursor` plan side by side. "It feels faster" is not evidence; "the leading `$match` now appears inside `$cursor` on an index scan, and the limit is folded into the sort" is.