Set Granularity for Time Series Data

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:

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 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.

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.