Docs Menu

Docs HomeMongoDB Manual

Set Granularity for Time Series Data

On this page

  • Retrieve the granularity of a Time Series Collection
  • Change the granularity of a Time Series Collection

When you create a time series collection, MongoDB automatically creates a system.buckets system collection based on the granularity value you specify, and groups documents into those buckets.


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.

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

Covered Time Span
"seconds" (default)
one hour
24 hours
30 days

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". This accurately reflects the polling interval for a data source.

timeseries: {
timeField: "timestamp",
metaField: "metadata",
granularity: "minutes"
expireAfterSeconds: 86400

Setting the granularity to hours would group 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 would lead to multiple buckets per polling interval, many of which might contain only a single document.


See also:

To retrieve the current value of granularity, use the listCollections command:

db.runCommand( { listCollections: 1 } )

The result document contains a document for the time series collection which contains the options.timeseries.granularity field.

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

To change the granularity value, issue the following collMod command:

collMod: "weather24h",
timeseries: { granularity: "hours" }

Once set, you cannot decrease granularity. For example, if granularity is set to minutes, you can increase it to hours, but you cannot decrease it to seconds.


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 →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.