MongoDB Bucket Pattern: Optimize Time-Series Storage (2026)

The MongoDB Bucket Pattern is a clever way to manage time-series data that avoids the typical performance pitfalls of storing millions of individual documents.

Let’s see it in action. Imagine we’re tracking sensor readings from IoT devices. Without bucketing, each reading might be a separate document:

{
  "_id": ObjectId("..."),
  "deviceId": "sensor-001",
  "timestamp": ISODate("2023-10-27T10:00:00Z"),
  "temperature": 22.5,
  "humidity": 45.2
}

If you have millions of these, queries for a specific device over a day, week, or month can become incredibly slow. Indexes help, but the sheer number of documents to scan is the killer.

The Bucket Pattern groups these individual readings into larger "bucket" documents. Each bucket represents a fixed time interval (e.g., 1 hour, 1 day).

Here’s what a bucket document might look like:

{
  "_id": ObjectId("..."),
  "deviceId": "sensor-001",
  "bucketStart": ISODate("2023-10-27T10:00:00Z"), // Start of the hour bucket
  "bucketEnd": ISODate("2023-10-27T11:00:00Z"),   // End of the hour bucket
  "data": [
    { "timestamp": ISODate("2023-10-27T10:01:15Z"), "temperature": 22.6, "humidity": 45.3 },
    { "timestamp": ISODate("2023-10-27T10:05:30Z"), "temperature": 22.5, "humidity": 45.1 },
    // ... up to N readings
  ]
}

The data field is an array holding the individual readings that fall within the bucketStart and bucketEnd times.

This pattern solves the problem of query performance. Instead of scanning millions of individual documents, you’re now scanning a much smaller number of bucket documents. To get readings for sensor-001 between 10:00 AM and 11:00 AM on October 27th, 2023, you’d query for documents where deviceId is "sensor-001" and bucketStart is ISODate("2023-10-27T10:00:00Z"). The database retrieves a single bucket document, and then you process the array within your application.

The key levers you control are:

1. Bucket Size: This is the most critical decision. Too small, and you don’t gain much. Too large, and the data array within a single bucket becomes too big, impacting performance when you need to process that array. Common choices are 1 hour, 6 hours, or 1 day for high-frequency data.
2. deviceId (or other grouping key): You’ll typically want to partition data not just by time but also by the entity generating the data (like a device, user, or server). This ensures queries for a specific entity only hit relevant buckets.
3. Indexing: You’ll need indexes on deviceId and bucketStart (or your chosen time field) to efficiently find the correct buckets. A compound index like { "deviceId": 1, "bucketStart": 1 } is standard.

The system automatically handles populating these buckets. You’d typically have an application service that receives incoming readings. This service checks if a bucket for the given deviceId and time interval already exists. If it does, it appends the new reading to the data array. If not, it creates a new bucket document with the current reading as the first entry.

A common implementation detail is to have a background process that "closes" buckets after they’ve been filled and are no longer expected to receive new data. This can optimize storage and querying by preventing updates to older buckets.

The real magic of bucketing is how it transforms read operations. Instead of fetching potentially millions of documents and then filtering/aggregating them, you fetch a handful of buckets and then perform a simple array search or iteration within your application code. This drastically reduces I/O and network traffic.

The primary challenge with the bucket pattern is managing the bucket size. If your data ingestion rate fluctuates wildly, you might end up with some buckets that are almost empty and others that are excessively large, potentially exceeding BSON document size limits if not carefully managed.

The next step in optimizing time-series data often involves exploring MongoDB’s Time Series Collections, which automate many of these bucketing concerns.