Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Set Granularity for Time Series Data

On this page

  • Retrieve the Current Bucketing Parameters
  • Using the "granularity" Parameter
  • Using Custom Bucketing Parameters
  • Change Time Series Granularity

When you create a time series collection, MongoDB automatically creates a system.buckets system collection and groups incoming time series data into buckets. By setting granularity, you control how frequently data is bucketed based on the ingestion rate of your data.

Starting in MongoDB 6.3, you can use the custom bucketing parameters bucketMaxSpanSeconds and bucketRoundingSeconds to specify bucket boundaries and more accurately control how time series data is bucketed.

Note

You must be running MongoDB 5.0.1 or later in order to change a time series collection's granularity after the collection has been created. See MongoDB 5.0 known issues.

To retrieve current collection values, use the listCollections command:

db.runCommand( { listCollections: 1 } )

For time series collections, the output contains granularity, bucketMaxSpanSeconds, and bucketRoundingSeconds parameters, if present.

{
cursor: {
id: <number>,
ns: 'test.$cmd.listCollections',
firstBatch: [
{
name: <string>,
type: 'timeseries',
options: {
expireAfterSeconds: <number>,
timeseries: {
timeField: <string>,
metaField: <string>,
granularity: <string>,
bucketMaxSpanSeconds: <number>,
bucketRoundingSeconds: <number>
}
},
...
},
...
]
}
}

The following table shows the maximum time interval included in one bucket of data when using a given granularity value:

granularity
granularity bucket limit
seconds
1 hour
minutes
24 hours
hours
30 days

By default, granularity is set to seconds. You can improve performance by setting the granularity value to the closest match to the time span between incoming measurements from the same data source. For example, if you are recording weather data from thousands of sensors but only record data from each sensor once per 5 minutes, set granularity to "minutes".

db.createCollection(
"weather24h",
{
timeseries: {
timeField: "timestamp",
metaField: "metadata",
granularity: "minutes"
},
expireAfterSeconds: 86400
}
)

Setting the granularity to hours groups up to a month's worth of data ingest events into a single bucket, resulting in longer traversal times and slower queries. Setting it to seconds leads to multiple buckets per polling interval, many of which might contain only a single document.

Tip

See also:

In MongoDB 6.3 and higher, instead of granularity, you can set bucket boundaries manually using the two custom bucketing parameters. Consider this approach if you expect to query data for fixed time intervals, such as every 4 hours starting at midnight. Ensuring buckets don't overlap between those periods optimizes for high query volume and insert operations.

To use custom bucketing parameters, set both parameters to the same value, and do not set granularity:

  • bucketMaxSpanSeconds sets the maximum time between timestamps in the same bucket. Possible values are 1-31536000.

  • bucketRoundingSeconds sets the time interval that determines the starting timestamp for a new bucket. When a document requires a new bucket, MongoDB rounds down the document's timestamp value by this interval to set the minimum time for the bucket.

For the weather station example, if you generate summary reports every 4 hours, you could adjust bucketing by setting the custom bucketing parameters to 14400 seconds instead of using a granularity of "minutes":

db.createCollection(
"weather24h",
{
timeseries: {
timeField: "timestamp",
metaField: "metadata",
bucketMaxSpanSeconds: 14400,
bucketRoundingSeconds: 14400
}
}
)

If a document with a time of 2023-03-27T16:24:35Z does not fit an existing bucket, MongoDB creates a new bucket with a minimum time of 2023-03-27T16:00:00Z and a maximum time of 2023-03-27T19:59:59Z.

You can increase timeseries.granularity from a shorter unit of time to a longer one using a collMod command.

db.runCommand( {
collMod: "weather24h",
timeseries: { granularity: "seconds" | "minutes" | "hours" }
} )

If you are using the custom bucketing parameters bucketRoundingSeconds and bucketMaxSpanSeconds instead of granularity, include both custom parameters in the collMod command and set them to the same value:

db.runCommand( {
collMod: "weather24h",
timeseries: {
bucketRoundingSeconds: 86400,
bucketMaxSpanSeconds: 86400
}
} )

You cannot decrease the granularity interval or the custom bucketing values.

Note

To modify the granularity of a sharded time series collection, you must be running MongoDB 6.0 or later.

←  Set up Automatic Removal for Time Series Collections (TTL)Add Secondary Indexes to Time Series Collections →