Bucket pattern for time-series data in MongoDB

Introduction

The bucket pattern groups many time-series records into one document to save space and improve query speed.

When you collect sensor readings every second and want to store them efficiently.

When you track user activity logs over time and want to reduce the number of documents.

When you monitor server metrics and want faster queries on recent data.

When you want to reduce storage costs by grouping many small events.

When you need to quickly find data for a specific time range.

Syntax

MongoDB

db.collection.aggregate([
  {
    $bucket: {
      groupBy: "$timeField",
      boundaries: [start1, start2, ..., startN],
      default: "other",
      output: {
        count: { $sum: 1 },
        data: { $push: "$dataField" }
      }
    }
  }
])

$bucket groups documents by ranges you define in boundaries.

The groupBy field is usually a date or time field.

Examples

This groups readings into January and February buckets, counting and collecting values.

MongoDB

db.readings.aggregate([
  {
    $bucket: {
      groupBy: "$timestamp",
      boundaries: [ISODate("2024-01-01"), ISODate("2024-02-01"), ISODate("2024-03-01")],
      default: "Other",
      output: {
        count: { $sum: 1 },
        readings: { $push: "$value" }
      }
    }
  }
])

This groups events by hour intervals (0-1h, 1-2h, 2-3h) after midnight.

MongoDB

db.logs.aggregate([
  {
    $bucket: {
      groupBy: "$eventTime",
      boundaries: [0, 3600, 7200, 10800],
      default: "Other",
      output: {
        events: { $push: "$event" },
        total: { $sum: 1 }
      }
    }
  }
])

Sample Program

This example inserts temperature readings at different times and groups them into 1-hour buckets, counting readings and collecting their values.

MongoDB

db.temperatureReadings.insertMany([
  { timestamp: ISODate("2024-06-01T00:10:00Z"), value: 22 },
  { timestamp: ISODate("2024-06-01T00:20:00Z"), value: 23 },
  { timestamp: ISODate("2024-06-01T01:05:00Z"), value: 21 },
  { timestamp: ISODate("2024-06-01T01:45:00Z"), value: 20 },
  { timestamp: ISODate("2024-06-01T02:15:00Z"), value: 19 }
])

db.temperatureReadings.aggregate([
  {
    $bucket: {
      groupBy: "$timestamp",
      boundaries: [
        ISODate("2024-06-01T00:00:00Z"),
        ISODate("2024-06-01T01:00:00Z"),
        ISODate("2024-06-01T02:00:00Z"),
        ISODate("2024-06-01T03:00:00Z")
      ],
      default: "Other",
      output: {
        count: { $sum: 1 },
        values: { $push: "$value" }
      }
    }
  }
])

Important Notes

The boundaries array must be sorted and cover all expected time ranges.

Documents with groupBy values outside boundaries go to the default bucket.

This pattern reduces the number of documents and speeds up queries on time ranges.

Summary

The bucket pattern groups many time-series records into fewer documents.

It uses $bucket with time boundaries to organize data.

This helps save space and makes queries on time ranges faster.