MongoDB $bucket Stage

Example 1 — Sample Data

Imagine six products with different prices, plus one gift card with null price for the default bucket.

db.products.insertMany([
  { _id: 1, name: "Pen", price: 2, score: 78 },
  { _id: 2, name: "Notebook", price: 8, score: 85 },
  { _id: 3, name: "Headphones", price: 45, score: 91 },
  { _id: 4, name: "Keyboard", price: 75, score: 88 },
  { _id: 5, name: "Monitor", price: 220, score: 94 },
  { _id: 6, name: "Laptop", price: 899, score: 96 },
  { _id: 7, name: "Gift card", price: null, score: 70 }
]);

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps seven documents in products. Run find() to see them:

db.products.find()

[
  { _id: 1, name: "Pen", price: 2, score: 78 },
  { _id: 2, name: "Notebook", price: 8, score: 85 },
  { _id: 3, name: "Headphones", price: 45, score: 91 },
  { _id: 4, name: "Keyboard", price: 75, score: 88 },
  { _id: 5, name: "Monitor", price: 220, score: 94 },
  { _id: 6, name: "Laptop", price: 899, score: 96 },
  { _id: 7, name: "Gift card", price: null, score: 70 }
]

Read the important fields like this:

How It Works

1. Insert once. insertMany adds seven product documents to products.
2. Prices span several bands. Cheap items, mid-tier, expensive, and one null.
3. find() shows the same shape. Ready for $bucket next.

Example 2 — Price Histogram

Goal: count products in [0, 50), [50, 100), and [100, 500), with outliers in Other.

db.products.aggregate([
  {
    $bucket: {
      groupBy: "$price",
      boundaries: [0, 50, 100, 500],
      default: "Other",
      output: {
        count: { $sum: 1 }
      }
    }
  },
  { $sort: { _id: 1 } }
]);

{ _id: 0, count: 3 }
{ _id: 50, count: 1 }
{ _id: 100, count: 1 }
{ _id: "Other", count: 2 }

How It Works

1. Evaluate price. Each product gets a numeric (or null) value from Example 1.
2. Match a half-open range. Pen/Notebook/Headphones → _id: 0; Keyboard → 50; Monitor → 100.
3. Use default for the rest. Laptop (899 ≥ 500) and Gift card (null) → "Other".
4. Count per bucket. $sum: 1 tallies documents in each band.

Example 3 — Custom Output

Same boundaries, but also compute average score and list product names in each bucket.

db.products.aggregate([
  {
    $bucket: {
      groupBy: "$price",
      boundaries: [0, 50, 100, 500],
      default: "Other",
      output: {
        count: { $sum: 1 },
        avgScore: { $avg: "$score" },
        items: { $push: "$name" }
      }
    }
  },
  { $sort: { _id: 1 } }
]);

{
  _id: 0,
  count: 3,
  avgScore: 84.66666666666667,
  items: ["Pen", "Notebook", "Headphones"]
}
{
  _id: 50,
  count: 1,
  avgScore: 88,
  items: ["Keyboard"]
}
{
  _id: 100,
  count: 1,
  avgScore: 94,
  items: ["Monitor"]
}
{
  _id: "Other",
  count: 2,
  avgScore: 83,
  items: ["Laptop", "Gift card"]
}

How It Works

1. Same bucket assignment. Still using the ranges from Example 2.
2. Accumulators per bucket. $avg and $push work like fields in $group.
3. Dashboard-ready rows. Each band returns count, average score, and item names.
4. Easy check. Bucket 0 should list Pen, Notebook, and Headphones.