How does $facet let one pipeline compute several independent aggregations over the same input?

## The problem it solves A faceted search page needs several different summaries of the *same* filtered result set: the current page of documents, the total match count for pagination, and counts per category, per price band, per brand for the filter sidebar. Running those as separate queries means re-executing the same filter several times and risking inconsistency if data changes between calls. `$facet` computes them in one pass over one input stream. ## Shape ```javascript db.products.aggregate([ { $match: { category: "laptops", inStock: true } }, { $facet: { page: [ { $sort: { price: 1 } }, { $skip: 0 }, { $limit: 20 } ], total: [ { $count: "n" } ], byBrand: [ { $sortByCount: "$brand" } ], byPrice: [ { $bucket: { groupBy: "$price", boundaries: [0, 500, 1000, 2000], default: "2000+", output: { n: { $sum: 1 } } } } ] } } ]) ``` The output is **one** document: ```json { "page": [ /* 20 docs */ ], "total": [ { "n": 137 } ], "byBrand": [ { "_id": "acme", "count": 40 }, … ], "byPrice": [ { "_id": 0, "n": 12 }, … ] } ``` Note the shapes: every facet is an array, even when it holds one element. `total` is `[{ n: 137 }]`, not `137`, and a `$count` facet over an empty input produces an **empty array** — application code that reads `total[0].n` blindly will throw on a zero-result search. Reading it defensively, or unwrapping it with a following `{ $set: { total: { $ifNull: [{ $arrayElemAt: ["$total.n", 0] }, 0] } } }`, is the usual fix. ## Same input, independent pipelines Each sub-pipeline sees exactly the documents that arrived at the `$facet` stage, unaffected by what the other sub-pipelines do. That independence is the whole point, and it is also the reason `$facet` cannot reduce the work: the input is materialised once and fed to every branch, so ten facets mean ten traversals of that materialised set. ## The three constraints worth naming **Single-document output and the 16 MB limit.** Because all facets land in one BSON document, their combined size is bounded by the 16 MB document limit. A facet that returns unbounded results — no `$limit`, or a `$group` producing millions of buckets — will make the whole aggregation fail, taking the useful facets down with it. Every facet should have a bound: a `$limit`, a `$count`, or a grouping key with known low cardinality. **No index use inside.** MongoDB documents that `$facet` and its sub-pipelines cannot make use of indexes, even when a sub-pipeline starts with `$match`. Practically: the selective filter goes **before** the `$facet`, where the planner can pick an index; a `$match` inside a facet is a per-document filter over the already-materialised input. Getting this backwards — putting the search predicate inside each facet — is the classic performance bug with this stage. **Disallowed stages.** Sub-pipelines cannot nest another `$facet`, and cannot write with `$out` or `$merge`. Stages that must be first in a pipeline, such as `$geoNear` and the `$…Stats` diagnostics, are also unavailable inside. ## $bucket and $bucketAuto, the usual facet contents `$bucket` groups documents into ranges you specify: `groupBy` is the expression, `boundaries` is a sorted array of same-type edges (each bucket is lower-inclusive, upper-exclusive), `output` holds accumulators exactly as in `$group`, and `default` names the bucket for values falling outside the boundaries. Without a `default`, a document outside the boundaries makes the stage **error** — a real production hazard when new data drifts past your highest edge, and a good reason to always supply one. `$bucketAuto` instead takes a `buckets` count and picks boundaries itself to distribute documents as evenly as it can, with an optional `granularity` that snaps edges to a preferred number series. Use `$bucket` when the ranges are business-defined (price bands you display), `$bucketAuto` when you just want an even distribution for a histogram. ## When not to use it `$facet` is the right answer when the facets genuinely share an input and you want one round trip and one consistent snapshot. It is the wrong answer when one facet is expensive and the others are cheap but you need them at different cadences — sidebar counts often change slowly and can be cached or pre-aggregated, while the result page must be live. It is also the wrong answer for a plain "results plus total count" pair on a very large match set, where computing an exact total is the expensive part regardless of stage; approximate or capped counts are the usual production compromise. And note that a page of results plus its total is fundamentally offset pagination — for deep pages, keyset paging outperforms it, facet or not.