Docsp 28718 forwardport (#3144)

* Codeblock rendering fix

* Self proofreading

* Clarified restrictions on bucketing parameters

* Switching to procedure directive

* Switching to procedure directive

* Internal PR feedback

* Internal review feedback

* Internal review feedback--amend

* Internal review feedback--amend

* Internal review feedback--amend

* External review feedback

* Merge cleanup

Author: nvillahermosa-mdb

source/core/timeseries/timeseries-best-practices.txt

@@ -215,33 +215,33 @@ Optimize Query Performance
 
 Set Appropriate Bucket Granularity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When you create a :ref:`time series collection 
-<manual-timeseries-collection>`, MongoDB groups incoming time series
-data into buckets. By accurately setting granularity, you control how 
-frequently data is bucketed based on the ingestion rate of your data.
+When you create a time series collection, MongoDB groups incoming time
+series data into buckets. By accurately setting granularity, you control
+how frequently data is bucketed based on the ingestion rate of your data.
 
 Starting in MongoDB 6.3, you can use the custom bucketing parameters
 ``bucketMaxSpanSeconds`` and ``bucketRoundingSeconds`` to specify bucket
-boundaries and more accurately control how time series data is bucketed.
+boundaries and more precisely control how time series data is bucketed.
 
 You can improve performance by setting the ``granularity`` or custom
 bucketing parameters to the best match for 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, you can either set ``granularity``
-to ``"minutes"`` or set the custom bucketing parameters to ``300`` (seconds).
-
-The following table shows the maximum time interval included in one 
-bucket of data when using a given ``granularity`` value:
-
-.. include:: /includes/table-timeseries-granularity-intervals.rst
+to ``"minutes"`` or set the custom bucketing parameters to ``300``
+(seconds).
 
 In this case, 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.
 
+The following table shows the maximum time interval included in one 
+bucket of data when using a given ``granularity`` value:
+
+.. include:: /includes/table-timeseries-granularity-intervals.rst
+
 .. seealso::
 
    :ref:`Timing of Automatic Removal

source/core/timeseries/timeseries-granularity.txt

@@ -16,9 +16,8 @@ Set Granularity for Time Series Data
    :description: Time series, granularity, IOT
    :keywords: Time series, granularity, IOT
 
-When you create a :ref:`time series collection 
-<manual-timeseries-collection>`, MongoDB automatically creates a
-``system.buckets`` :ref:`system collection
+When you create a time series collection, MongoDB automatically creates
+a ``system.buckets`` :ref:`system collection 
 <metadata-system-collections>` and groups incoming time series data 
 into buckets. By setting granularity, you control how 
 frequently data is bucketed based on the ingestion rate of your data.
@@ -34,7 +33,7 @@ boundaries and more accurately control how time series data is bucketed.
    created. See :ref:`MongoDB 5.0 known issues
    <5.0-known-issue-granularity>`.
 
-Retrieve the Current bucketing parameters
+Retrieve the Current Bucketing Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To retrieve current collection values, use the
@@ -44,9 +43,8 @@ To retrieve current collection values, use the
 
    db.runCommand( { listCollections: 1 } )
 
-The result document contains a document for the time series collection
-which contains ``options.timeseries.granularity``,
-``options.timeseries.bucketMaxSpanSeconds``, and ``options.timeseries.bucketRoundingSeconds`` fields, if present.
+For time series collections, the output contains
+``granularity``, ``bucketMaxSpanSeconds``, and ``bucketRoundingSeconds`` fields, if present.
 
 .. code-block:: javascript
   :copyable: false
@@ -77,8 +75,8 @@ which contains ``options.timeseries.granularity``,
    }
 
 
-Using a Single ``granularity`` Field
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using the "granularity" Field
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following table shows the maximum time interval included in one 
 bucket of data when using a given ``granularity`` value:
@@ -121,13 +119,18 @@ might contain only a single document.
 Using Custom Bucketing Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Instead of ``granularity``, you can set bucket boundaries manually using
-the two custom bucketing parameters. Set both parameters to the
-same value, and do not set ``granularity``:
+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 need the additional precision to optimize 
+a high volume of queries and :dbcommand:`insert` operations.
 
-- ``bucketMaxSpanSeconds``, sets the maximum time between timestamps
+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``, the time interval that determines the 
+
+- ``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.
@@ -160,11 +163,6 @@ Change Time Series Granularity
 You can increase ``timeseries.granularity`` from a shorter unit of time
 to a longer one using a :dbcommand:`collMod` command.
 
-.. note::
-
-   To modify the granularity of a **sharded** time series collection,
-   you must be running MongoDB 6.0 or later.
-
 .. code-block:: javascript
 
    db.runCommand({
@@ -187,4 +185,10 @@ command and set them to the same value:
       }
    })
 
-You cannot decrease the granularity interval or the custom bucketing values.
+You cannot decrease the granularity interval or the custom bucketing
+values.
+
+.. note::
+
+   To modify the granularity of a **sharded** time series collection,
+   you must be running MongoDB 6.0 or later.

source/core/timeseries/timeseries-limitations.txt

@@ -150,24 +150,13 @@ parameters later.
 
 .. _timeseries-limitations-granularity:
 
-Modification of ``granularity``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After you set the ``granularity``, you can only increase it one level at
-a time. The ``granularity`` can change from ``"seconds"`` to
-``"minutes"`` or from ``"minutes"`` to ``"hours"``. Other changes are
-not allowed. 
-
-To change the ``granularity`` from ``"seconds"`` to ``"hours"``, first
-increase the ``granularity`` to ``"minutes"`` and then to ``"hours"``.
-
-Modification of Bucket Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Modifying 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:
+Once you set a collection's ``granularity`` or custom bucketing
+parameters ``bucketMaxSpanSeconds`` and ``bucketRoundingSeconds``, you
+can increase them, but not decrease them.
+Use the :dbcommand:`collMod` command to modify the parameters. For example:
 
 .. code-block:: javascript
 
@@ -178,8 +167,9 @@ and ``bucketRoundingSeconds`` parameters. For example:
 
 .. note::
 
-   The ``bucketMaxSpanSeconds`` and ``bucketRoundingSeconds`` parameters must be
-   equal. If you modify one parameter, you must also modify the other.
+   ``bucketMaxSpanSeconds`` and ``bucketRoundingSeconds`` must be
+   equal. If you modify one parameter, you must also set the other to
+   the same value.
 
 .. _time-series-limitations-sharding: