Set Granularity for Time Series Data
On this page
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.
Retrieve the Current Bucketing Parameters
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> } }, ... }, ... ] } }
Using the "granularity" Parameter
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.
Using Custom Bucketing Parameters
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 need the additional precision to optimize
a high volume of queries 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 with 5 minute sensor intervals, you
could adjust bucketing by setting the custom bucketing parameters to
300 seconds, instead of using a granularity
of "minutes"
:
db.createCollection( "weather24h", { timeseries: { timeField: "timestamp", metaField: "metadata", bucketMaxSpanSeconds: 300, bucketRoundingSeconds: 300 } } )
If a document with a time of 2023-03-27T18:24:35Z
does not fit an
existing bucket, MongoDB creates a new bucket with a minimum time of
2023-03-27T18:20:00Z
and a maximum time of 2023-03-27T18:24:59Z
.
Change Time Series Granularity
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.