Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 70 ยท Aggregation pipeline

$facet, $bucket and Other Stages

Meet the utility stages of MongoDB aggregation: $facet, $bucket, $bucketAuto, $count, $sortByCount, $sample, $replaceRoot, $unionWith, $merge and $out.

You already know the workhorse stages: $match, $group, $project, $sort, $limit, $unwind and $lookup. MongoDB ships a second layer of stages that save you from writing long $group expressions: they count, bucket values into ranges, run several sub-pipelines at once, pick random documents and write results to another collection.

This lesson tours the most useful ones. Everything that returns data is runnable in the stand-in below, which is a small pipeline runner written in JavaScript. The two stages that write data, $merge and $out, are real MongoDB only and shown read-only.

Counting and ranking

$count One document with the total.
$sortByCount Group by a value, count, sort.
1 / 3

A runner to practice with

The stand-in below executes a pipeline (an array of stage objects) against an array of documents. It supports $count, $sortByCount, $bucket, $bucketAuto, $sample, $replaceRoot, $facet, $unionWith and a few helpers ($sort, $limit). It is far smaller than the real server: field paths like "$price" are supported only as plain top-level names, and $sample uses a fixed seed so results are repeatable, whereas the real stage is random every time. We reuse this runner in the TryIts that follow; because each TryIt is self-contained, the runner code is repeated in each.

$count and $sortByCount

$count replaces the whole stream with a single document holding the number of documents it received. { $count: "total" } outputs { total: 12 }. If nothing arrives, it outputs no document at all, not a zero, which surprises people: handle an empty result in your application.

$sortByCount is shorthand for a very common three-step recipe. { $sortByCount: "$category" } means group by category, count the documents in each group, and sort by that count, largest first:

JavaScript
db.products.aggregate([ { $sortByCount: "$category" } ])
// same as:
// { $group: { _id: "$category", count: { $sum: 1 } } }, { $sort: { count: -1 } }

Use it for "most common tags", "orders per status" and similar frequency tables.

$bucket and $bucketAuto

$bucket groups documents into ranges that you define. groupBy is the expression to classify, boundaries is a sorted list where each bucket includes its lower bound and excludes its upper bound, default collects everything outside the boundaries (without it, a value outside the ranges is an error), and output holds accumulators like in $group.

JavaScript
db.products.aggregate([
  { $bucket: {
      groupBy: "$price",
      boundaries: [0, 25, 50, 100],
      default: "100 or more",
      output: { count: { $sum: 1 }, names: { $push: "$name" } }
  } }
])

Each result has an _id equal to the bucket's lower boundary (or the default label). $bucketAuto removes the guesswork: you give it buckets: 4 and MongoDB splits the documents into four groups of roughly equal size, reporting each range as _id: { min, max }. The real stage can also snap boundaries to "nice" numbers with a granularity option; the stand-in below does a plain equal-count split and ignores that.

JS $count, $sortByCount, $bucket, $bucketAuto

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Look at the $bucket result: six items (Pen, Notebook, Stapler, Mug, Bottle and Map) land in the 0 bucket (prices 0 up to but not including 25), and the three expensive ones fall into "100 or more". A value of exactly 25 would start the next bucket, because lower bounds are inclusive.

$facet: several reports in one pass

Dashboards often need a total, a price histogram and the top three items at the same time. Running three separate queries scans the data three times. $facet takes the incoming documents once and feeds the same stream into several named sub-pipelines, returning a single document whose fields are arrays of each sub-pipeline's output.

JavaScript
db.products.aggregate([
  { $match: { category: "home" } },
  { $facet: {
      total:    [ { $count: "n" } ],
      byPrice:  [ { $bucket: { groupBy: "$price", boundaries: [0, 50, 100, 500] } } ],
      cheapest: [ { $sort: { price: 1 } }, { $limit: 2 }, { $project: { _id: 0, name: 1, price: 1 } } ]
  } }
])

Two rules matter. First, a $facet result is one document, so it must fit in 16 MB: use it for summaries, not for returning thousands of rows. Second, sub-pipelines cannot use indexes (the stage works on the output of the previous stages), so put your $match before the $facet to shrink the input. Some stages are not allowed inside a facet, including $out, $merge and $facet itself.

$replaceRoot, $sample and $unionWith

$replaceRoot throws away the current document and promotes a subdocument to the top level: { $replaceRoot: { newRoot: "$address" } } turns { name, address: { city, zip } } into { city, zip }. It is the stage to use after $unwind when each element becomes a document in its own right. ($replaceWith is the same stage under a shorter name.)

$sample: { size: 3 } returns three random documents, useful for spot checks and "random product" widgets. On big collections avoid sampling more than a small fraction of the data, as the server may fall back to a slower method.

$unionWith appends the documents of another collection, optionally after running a pipeline on them, like SQL's UNION ALL. It does not remove duplicates.

The second stand-in combines $replaceRoot, $unionWith, a seeded $sample, and $facet.

JS $facet, $replaceRoot, $unionWith, $sample

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Writing results: $out and $merge

Two stages make a pipeline write. They must be the last stage and cannot run in this tutorial's stand-in, so here they are as real MongoDB code only:

JavaScript
// $out replaces the target collection with the pipeline result
db.orders.aggregate([
  { $group: { _id: "$customerId", spent: { $sum: "$total" } } },
  { $out: "customer_totals" }
])

// $merge updates or inserts into an existing collection, matching on a key
db.orders.aggregate([
  { $group: { _id: "$customerId", spent: { $sum: "$total" } } },
  { $merge: { into: "customer_totals", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } }
])

$out is all-or-nothing: it replaces the whole target collection. $merge is incremental, with whenMatched choices such as replace, merge, keepExisting or fail, which makes it the tool for refreshing a summary collection (a "materialized view") on a schedule. Both let you precompute expensive reports once and serve them with cheap reads.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is { $sortByCount: "$status" } shorthand for?

    It groups by the expression, counts each group and sorts the groups by count, largest first.
  2. 2. In $bucket with boundaries [0, 25, 50, 100], which bucket holds a document with price 25?

    Lower bounds are inclusive and upper bounds are exclusive, so 25 belongs to the bucket that starts at 25.
  3. 3. What does $facet return?

    All facets read the same input and their results are packed into a single output document, which is why it must stay under 16 MB.
  4. 4. Which statement about $out and $merge is correct?

    Both write the result and must come last. $out replaces the collection, while $merge can insert or update documents by key. Neither is allowed inside $facet.

Summary

  • $count and $sortByCount answer "how many" and "which value is most common" without a hand-written $group.
  • $bucket uses your boundaries (lower inclusive, upper exclusive, default for strays); $bucketAuto picks roughly equal-sized ranges.
  • $facet runs several sub-pipelines on one input and returns one document, so match first and keep summaries small.
  • $replaceRoot, $sample and $unionWith reshape, sample and combine streams.
  • $out and $merge write results and must be last; $merge refreshes summary collections incrementally.

Next, rank and accumulate across neighboring documents with Window Functions and Advanced Aggregation.