Set Granularity for Time Series Data设置时间序列数据的粒度

Retrieve the Current Bucketing Parameters检索当前桶形参数

To retrieve current collection values, use the listCollections command:要检索当前集合值，请使用listCollections命令：

db.runCommand( { listCollections: 1 } )

For time series collections, the output contains granularity, bucketMaxSpanSeconds, and bucketRoundingSeconds parameters, if present.对于时间序列集合，输出包含granularity、bucketMaxSpanSeconds和bucketRoundingSeconds参数（如果存在）。

{
    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值时一个数据桶中包含的最大时间间隔：

By default, granularity is set to seconds. 默认情况下，granularity设置为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. 您可以通过将granularity值设置为与来自同一数据源的传入测量值之间的时间跨度最匹配来提高性能。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".例如，如果您正在记录数千个传感器的天气数据，但每5分钟只记录一次每个传感器的数据，请将granularity设置为"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. 将granularity设置为hours将最多一个月的数据摄取事件分组到一个桶中，导致遍历时间更长，查询速度较慢。Setting it to seconds leads to multiple buckets per polling interval, many of which might contain only a single document.将其设置为seconds会导致每个轮询间隔有多个桶，其中许多桶可能只包含一个文档。

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. 在MongoDB 6.3及更高版本中，您可以使用两个自定义的bucketing参数手动设置桶边界，而不是granularity。Consider this approach if you need the additional precision to optimize a high volume of queries and insert operations.如果您需要额外的精度来优化大量的查询和insert操作，请考虑这种方法。

To use custom bucketing parameters, set both parameters to the same value, and do not set granularity:要使用自定义分段参数，请将两个参数设置为相同的值，并且不要设置granularity：

• bucketMaxSpanSeconds sets the maximum time between timestamps in the same bucket. Possible values are 1-31536000.设置同一桶中时间戳之间的最大时间。可能的值为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.设置时间间隔，用于确定新桶的开始时间戳。当文档需要一个新的桶时，MongoDB会将文档的时间戳值四舍五入这个间隔，以设置桶的最短时间。

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":对于传感器间隔为5分钟的气象站示例，您可以通过将自定义桶形参数设置为300秒来调整桶形，而不是使用"minutes"的granularity：

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.如果时间为2023-03-27T18:24:35Z的文档不适合现有的桶，MongoDB会创建一个新桶，最小时间为2023-03-27T18:20:00Z，最大时间为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.您可以使用collMod命令将timeseries.granularity从较短的时间单位增加到较长的时间单位。

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:如果您使用的是自定义bucketRoundingSeconds和bucketMaxSpanSeconds参数而不是granularity，请在collMod命令中包括这两个自定义参数，并将它们设置为相同的值：

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

You cannot decrease the granularity interval or the custom bucketing values.不能减少粒度间隔或自定义分段值。