Merge DOCS-15691 to v6.3: Additional timeseries options - bucketMaxSpanSeconds and bucketRoundingSeconds (#2143)

* Changes to granularity and addition of two timeseries options

* Add context about bucketing

* resolve merge conflict

* copy review feedback

* copy review 2

* tech review feedback

* update release notes

Author: davidhou17

source/core/timeseries/timeseries-granularity.txt

@@ -24,10 +24,19 @@ Set Granularity for Time Series Data
    <5.0-known-issue-granularity>`.
 
 When you create a :ref:`time series collection
-<manual-timeseries-collection>`, set the granularity to the value that
-is the closest match to the time span between consecutive incoming
-measurements that have the same unique value for the ``metaField``
-field:
+<manual-timeseries-collection>`, you can specify the
+``granularity`` parameter. The ``granularity`` determines how data 
+in the time series collection is stored internally. For details about 
+how MongoDB stores time series data, see :ref:`flexible-bucketing`.
+ 
+By default, ``granularity`` is set to ``"seconds"``. To optimize  
+data storage, set the ``granularity`` to a value that is closest 
+to the ingestion rate for your data source as specified by
+the ``metaField`` field. The ingestion rate is the time span between 
+consecutive incoming measurements that have the same unique value for 
+the ``metaField``.
+
+Consider the following example:
 
 .. code-block:: javascript
 
@@ -43,19 +52,12 @@ field:
        }
    )
 
-Setting the ``granularity`` parameter accurately improves performance by
-optimizing how data in the time series collection is stored internally.
-
-To set the parameter accurately, choose a ``granularity`` value that is
-closest to the ingestion rate for a unique data source as specified by
-the value for the ``metaField`` field.
-
-For example, if your ``metaField`` data identifies weather sensors and
+If your ``metaField`` data identifies weather sensors and
 you ingest data from each individual sensor once every 5 minutes, you
 should choose ``"minutes"``. Even if you have thousands of sensors and
 the data coming in from different sensors is only seconds apart, the
 ``granularity`` should still be based on the ingestion rate for one
-sensor that is uniquely identified by its metadata.
+sensor that is uniquely identified by its metadata. 
 
 In the following table, you can see the max time span of data that is
 stored together for each ``granularity`` value:
@@ -148,3 +150,57 @@ a time. From ``"seconds"`` to ``"minutes"`` or from ``"minutes"`` to
 
    You cannot modify the ``granularity`` of a sharded time series
    collection.
+
+.. _flexible-bucketing:
+
+Flexible Bucketing
+~~~~~~~~~~~~~~~~~~
+
+MongoDB groups incoming time series data into buckets. By setting the 
+``granularity`` parameter, you control how frequently data is bucketed 
+based on the ingestion rate of your data.
+
+Starting in MongoDB 6.3, you can specify the bucket boundaries to 
+more accurately control how time series data is bucketed. Use the 
+following parameters:
+
+- ``bucketMaxSpanSeconds``, the maximum time span between measurements
+  in a bucket.
+- ``bucketRoundingSeconds``, the time interval that determines the 
+  starting timestamp for a new bucket.
+
+.. note::
+
+   If you want to specify the bucket boundaries:
+
+   - You must set both ``bucketMaxSpanSeconds`` and ``bucketRoundingSeconds``.
+   - Both parameters must have the same value.
+   - You can't additionally set the ``granularity`` parameter.
+
+Consider the following time series collection:
+
+.. code-block:: javascript
+      
+   db. createCollection(
+      "weather24h", 
+      {
+         timeseries: {
+            timeField: "timestamp",
+            metaField: "metadata",
+            bucketMaxSpanSeconds: 60,
+            bucketRoundingSeconds: 60
+         }
+      }   
+   )
+
+Each bucket has a maximum time span of 60 seconds. When MongoDB opens a 
+new bucket, the starting timestamp is rounded down to the nearest 60-second 
+interval.
+
+For example, if you insert a new measurement into the collection with a
+timestamp of ``11:59:59``, the measurement is added to the bucket 
+with boundaries between ``11:59:00`` and ``12:00:00`` (non-inclusive).
+If the bucket doesn't exist, the starting timestamp of the new bucket 
+is determined by rounding ``11:59:59`` down to ``11:59:00``.
+
+For more information on time series parameters, see :ref:`time-series-fields`.

source/core/timeseries/timeseries-limitations.txt

@@ -169,6 +169,26 @@ a time. From ``"seconds"`` to ``"minutes"`` or from ``"minutes"`` to
 ``granularity`` from ``"seconds"`` to ``"hours"``, first increase the
 ``granularity`` to ``"minutes"`` and then to ``"hours"``.
 
+Modification of Bucket Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you set a collection's ``bucketMaxSpanSeconds`` and 
+``bucketRoundingSeconds`` parameters, they can only be increased. Use 
+the :dbcommand:`collMod` command to modify the ``bucketMaxSpanSeconds`` 
+and ``bucketRoundingSeconds`` parameters. For example:
+
+.. code-block:: javascript
+
+   db.runCommand({
+      collMod: "timeseries",
+      timeseries: { bucketMaxSpanSeconds: 3600, bucketRoundingSeconds: 3600 }
+   })
+   
+.. note::
+
+   The ``bucketMaxSpanSeconds`` and ``bucketRoundingSeconds`` parameters must be
+   equal. If you modify one parameter, you must also modify the other.
+
 .. _time-series-limitations-sharding:
 
 Sharding

source/core/timeseries/timeseries-procedures.txt

@@ -55,33 +55,31 @@ When creating a time series collection, specify the following options:
   :widths: 40 20 60
 
   * - Field
-
     - Type
-
     - Description
 
   * - ``timeseries.timeField``
-
     - string
-
     - .. include:: /includes/time-series/fact-time-field-description.rst
 
   * - ``timeseries.metaField``
-
     - string
-
     - .. include:: /includes/time-series/fact-meta-field-description.rst
 
   * - ``timeseries.granularity``
-
     - string
-
     - .. include:: /includes/time-series/fact-granularity-description.rst
 
-  * - ``expireAfterSeconds``
-
+  * - ``timeseries.bucketMaxSpanSeconds``
     - number
+    - .. include:: /includes/time-series/fact-bucket-max-span-description.rst
 
+  * - ``timeseries.bucketRoundingSeconds``
+    - number
+    - .. include:: /includes/time-series/fact-bucket-rounding-description.rst
+      
+  * - ``expireAfterSeconds``
+    - number
     - Optional. Enable the automatic deletion of documents in a
       :term:`time series collection` by specifying the number of seconds
       after which documents expire. MongoDB deletes expired documents

source/includes/time-series/fact-bucket-max-span-description.rst

@@ -0,0 +1,7 @@
+Optional. The maximum time span between measurements in a bucket.
+For more information, see :ref:`flexible-bucketing`.
+
+If you set this parameter:
+
+- ``timeseries.bucketRoundingSeconds`` must have the same value.
+- You can't set ``timeseries.granularity``.

source/includes/time-series/fact-bucket-rounding-description.rst

@@ -0,0 +1,8 @@
+Optional. The time interval that determines the starting 
+timestamp for a new bucket. For more information, see 
+:ref:`flexible-bucketing`.
+
+If you set this parameter:
+
+- ``timeseries.bucketMaxSpanSeconds`` must have the same value.
+- You can't set ``timeseries.granularity``.

source/includes/time-series/fact-granularity-description.rst

@@ -21,3 +21,6 @@ from the same source.
 
 If you do not specify ``timeseries.metaField``, consider the time
 span between all measurements that are inserted in the collection.
+
+If you set the ``granularity`` parameter, you can't set the 
+``bucketMaxSpanSeconds`` and ``bucketRoundingSeconds`` parameters.