How to Use $bucket in Aggregation in MongoDB: Syntax and Examples

In MongoDB aggregation, $bucket groups documents into user-defined ranges called buckets based on a specified expression. You define boundaries to set the ranges, and MongoDB counts or groups documents falling into each range. This helps summarize data by ranges like age groups or price intervals.

Syntax

The $bucket stage requires these main parts:

• groupBy: The expression to group documents by (e.g., a field).
• boundaries: An array defining the edges of each bucket range.
• default: (Optional) A bucket for values outside boundaries.
• output: (Optional) Defines fields to include in each bucket result.

json

{
  $bucket: {
    groupBy: <expression>,
    boundaries: [<lower1>, <upper1>, <upper2>, ...],
    default: <bucketName>,
    output: {
      <field1>: { <accumulator1> },
      <field2>: { <accumulator2> }
    }
  }
}

Example

This example groups sales documents by price ranges into buckets and counts how many sales fall into each price bucket.

mongodb

db.sales.aggregate([
  {
    $bucket: {
      groupBy: "$price",
      boundaries: [0, 100, 200, 300, 400],
      default: "Other",
      output: {
        count: { $sum: 1 },
        totalAmount: { $sum: "$price" }
      }
    }
  }
])

Output

[
  { "_id": 0, "count": 3, "totalAmount": 250 },
  { "_id": 100, "count": 2, "totalAmount": 350 },
  { "_id": 200, "count": 1, "totalAmount": 250 },
  { "_id": 300, "count": 0, "totalAmount": 0 },
  { "_id": "Other", "count": 1, "totalAmount": 500 }
]

Common Pitfalls

Common mistakes when using $bucket include:

• Not defining boundaries in ascending order, which causes errors.
• Missing the default bucket for values outside boundaries, leading to dropped documents.
• Using $bucket when $bucketAuto might be better for automatic bucket ranges.

mongodb

/* Wrong: boundaries not sorted */
db.collection.aggregate([
  {
    $bucket: {
      groupBy: "$value",
      boundaries: [100, 50, 200],
      default: "Other"
    }
  }
])

/* Right: boundaries sorted ascending */
db.collection.aggregate([
  {
    $bucket: {
      groupBy: "$value",
      boundaries: [50, 100, 200],
      default: "Other"
    }
  }
])

Quick Reference

Parameter	Description
groupBy	Expression to group documents by
boundaries	Array of bucket boundary values in ascending order
default	Bucket name for values outside boundaries (optional)
output	Fields and accumulators to include in each bucket (optional)

Key Takeaways

Use $bucket to group documents into defined ranges by specifying boundaries.

Boundaries must be sorted in ascending order to avoid errors.

Include a default bucket to catch values outside defined ranges.

Use output to calculate counts or sums per bucket.

$bucket is manual; consider $bucketAuto for automatic range grouping.