Docs Menu

Docs Home → Develop Applications → MongoDB 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.

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.

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

granularity
Covered Time Span
"seconds" (default)
one hour
"minutes"
24 hours
"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.

db.createCollection(
    "weather24h",
    {
       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.

Tip

See also:

Timing of Automatic Removal

Retrieve the granularity of a Time Series Collection

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>
               }
            },
            ...
         },
         ...
       ]
    }
 }

Change the granularity of a Time Series Collection

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

db.runCommand({
   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.

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 →

On this page