$bucket and $bucketAuto for distribution in MongoDB

Introduction

These operators help group data into ranges or buckets to see how values are spread out.

You want to see how many sales fall into different price ranges.

You want to group ages of people into age groups like 0-20, 21-40, etc.

You want to divide test scores into equal groups to compare performance.

You want to summarize data by ranges instead of exact values.

Syntax

MongoDB

db.collection.aggregate([
  {
    $bucket: {
      groupBy: <expression>,
      boundaries: [<lower1>, <lower2>, ..., <upper>],
      default: <optional-default-bucket>,
      output: { <field1>: { <accumulator1> }, ... }
    }
  }
])

// or

db.collection.aggregate([
  {
    $bucketAuto: {
      groupBy: <expression>,
      buckets: <number-of-buckets>,
      output: { <field1>: { <accumulator1> }, ... }
    }
  }
])

$bucket requires you to specify exact boundaries for the groups.

$bucketAuto automatically creates buckets with roughly equal numbers of documents.

Examples

This groups sales by price ranges: 0-99, 100-199, 200-299, and others.

MongoDB

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

This automatically divides sales into 3 buckets with about equal counts.

MongoDB

db.sales.aggregate([
  {
    $bucketAuto: {
      groupBy: "$price",
      buckets: 3,
      output: { count: { $sum: 1 } }
    }
  }
])

Sample Program

This groups products by quantity in stock into ranges 0-49, 50-99, 100-149, 150+.

MongoDB

db.products.aggregate([
  {
    $bucket: {
      groupBy: "$quantity",
      boundaries: [0, 50, 100, 150],
      default: "Other",
      output: { count: { $sum: 1 } }
    }
  }
])

Important Notes

Use $bucket when you know the exact ranges you want.

Use $bucketAuto when you want MongoDB to decide ranges for balanced groups.

The default bucket catches values less than the first boundary or invalid values in $bucket.

Summary

$bucket groups data by fixed ranges you define.

$bucketAuto groups data into balanced buckets automatically.

Both help understand how data is spread across ranges.