Docs 15475 coll mod disabled on bucket namespaces (#2096)

* DOCS-15475 collMod disabled on system.bucket namespace

* Updated with tech review feedback

* Updated with copy review feedback

* Renamed table include to adhere to conventions

Author: nvillahermosa-mdb

source/core/timeseries/timeseries-automatic-removal.txt

@@ -97,6 +97,7 @@ The result document contains a document for the time series collection
 which contains the ``options.expireAfterSeconds`` field.
 
 .. code-block:: javascript
+  :copyable: false
 
   {
       cursor: {

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

@@ -162,6 +162,7 @@ omit the empty fields from your documents.
 For example, consider the following documents:
 
 .. code-block:: javascript
+   :copyable: false
    :emphasize-lines: 7
 
    {
@@ -186,6 +187,7 @@ In contrast, the following documents where the empty array is omitted
 receive the benefit of optimal compression:
 
 .. code-block:: javascript
+   :copyable: false
 
    {
       time: 2020-01-23T00:00:00.441Z,

source/core/timeseries/timeseries-granularity.txt

@@ -16,18 +16,29 @@ 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 <metadata-system-collections>` 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 :ref:`MongoDB 5.0 known issues
    <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:
+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
+
+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.
 
 .. code-block:: javascript
 
@@ -43,43 +54,11 @@ 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
-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.
-
-In the following table, you can see the max time span of data that is
-stored together for each ``granularity`` value:
-
-.. list-table::
-  :header-rows: 1
-  :widths: 40 60
-
-  * - ``granularity``
-
-    - Covered Time Span
-
-  * - ``"seconds"`` (default)
-
-    - one hour
-
-  * - ``"minutes"``
-
-    - 24 hours
-
-  * - ``"hours"``
-
-    - 30 days
-
+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.
 
 .. seealso::
 
@@ -100,6 +79,7 @@ The result document contains a document for the time series collection
 which contains the ``options.timeseries.granularity`` field.
 
 .. code-block:: javascript
+  :copyable: false
 
   {
       cursor: {
@@ -128,8 +108,8 @@ which contains the ``options.timeseries.granularity`` field.
 Change the ``granularity`` of a Time Series Collection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To change the ``granularity`` parameter value, issue the following
-:dbcommand:`collMod` command:
+To change the ``granularity`` value, issue the following
+:dbcommand:`collMod` command: 
 
 .. code-block:: javascript
 
@@ -138,11 +118,9 @@ To change the ``granularity`` parameter value, issue the following
       timeseries: { granularity: "hours" }
    })
 
-Once the ``granularity`` is set it can only be increased by one level at
-a time. From ``"seconds"`` to ``"minutes"`` or from ``"minutes"`` to
-``"hours"``. Other changes are not allowed. If you need to change the
-``granularity`` from ``"seconds"`` to ``"hours"``, first increase the
-``granularity`` to ``"minutes"`` and then to ``"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::
 

source/core/timeseries/timeseries-migrate-data-into-timeseries-collection.txt

@@ -206,6 +206,7 @@ following command:
 The command returns the following output:
 
 .. code-block:: javascript
+   :copyable: false
 
    2021-06-01T16:48:39.980+0200  writing weather.temporarytimeseries to timeseries/weather/temporarytimeseries.bson
    2021-06-01T16:48:40.056+0200  done dumping weather.temporarytimeseries (10000 documents)
@@ -224,6 +225,7 @@ collection ``weathernew``, issue the following command:
 The command returns the following output:
 
 .. code-block:: javascript
+   :copyable: false
 
    2021-06-01T16:50:56.639+0200  checking for collection data in timeseries/weather/temporarytimeseries.bson
    2021-06-01T16:50:56.640+0200  restoring to existing collection weather.weathernew without dropping

source/core/timeseries/timeseries-procedures.txt

@@ -48,7 +48,7 @@ command:
 ``timeseries`` Object Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When creating a time series collection, specify the following options:
+When creating a time series collection, set the following fields:
 
 .. list-table::
   :header-rows: 1
@@ -240,6 +240,7 @@ measurement and then returns the average of all temperature measurements
 that day:
 
 .. code-block:: javascript
+   :copyable: false
 
    {
     "_id" : {

source/includes/table-timeseries-granularity-intervals.rst

@@ -0,0 +1,19 @@
+.. list-table::
+  :header-rows: 1
+  :widths: 40 60
+
+  * - ``granularity``
+
+    - Covered Time Span
+
+  * - ``"seconds"`` (default)
+
+    - one hour
+
+  * - ``"minutes"``
+
+    - 24 hours
+
+  * - ``"hours"``
+
+    - 30 days

source/reference/command/collMod.txt

@@ -56,9 +56,8 @@ or view in the current database.
 Options
 -------
 
-Index Options
-~~~~~~~~~~~~~
-
+Change Index Properties
+~~~~~~~~~~~~~~~~~~~~~~~
 
 .. collflag:: index
 
@@ -167,8 +166,8 @@ Index Options
 
       - :ref:`index-type-hidden`
 
-Document Validation
-~~~~~~~~~~~~~~~~~~~
+Validate Documents
+~~~~~~~~~~~~~~~~~~
 
 .. collflag:: validator
 
@@ -216,8 +215,8 @@ Document Validation
    To see an example that uses ``validationAction``, see
    :ref:`schema-validation-handle-invalid-docs`.
 
-Views
-~~~~~
+Modify Views
+~~~~~~~~~~~~
 
 .. note::
 
@@ -258,45 +257,78 @@ Views
         { $project: { user: 1, date: 1, description: 1} } ]
    } )
 
-Time Series Collections
-~~~~~~~~~~~~~~~~~~~~~~~
+Modify Time Series Collections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To enable automatic removal of documents or change the
-``expireAfterSeconds`` parameter value for an existing :ref:`time
-series collection <manual-timeseries-collection>`, issue the following
-:dbcommand:`collMod` command:
+.. collflag:: expireAfterSeconds
 
-.. code-block:: javascript
+   .. note::
 
-   db.runCommand( {
-      collMod: <collection>,
-      expireAfterSeconds: <Number> || "off"
-   } )
+      This is distinct from using the :collflag:`index` option with the
+      ``expireAfterSeconds`` property to change the expiration time
+      for a :ref:`TTL Collection <ttl-collections>`.
+
+   To enable automatic document removal or modify the current 
+   expiration interval for a :ref:`time series collection
+   <manual-timeseries-collection>`, change the ``expireAfterSeconds``
+   value:
 
-The ``expireAfterSeconds`` field must be either:
+   .. code-block:: javascript
 
-- A non-negative decimal number (``>=0``)
-- The string ``"off"``.
+      db.runCommand( {
+         collMod: <collection>,
+         expireAfterSeconds: <number> || "off"
+      } )
 
-A number specifies the number of seconds after which documents expire.
-The string ``"off"`` removes the ``expireAfterSeconds`` parameter and
-disables automatic removal.
+   Set ``expireAfterSeconds`` to ``"off"`` to disable automatic removal,
+   or a non-negative decimal number (``>=0``) to specify the number of
+   seconds after which documents expire.
 
 .. seealso::
 
    :ref:`manual-timeseries-automatic-removal`
 
+.. collflag:: timeseries-granularity
+
+   To modify the :ref:`granularity <timeseries-granularity>` of a time 
+   series collection, change the ``timeseries.granularity`` value:
+
+   .. code-block:: javascript
+
+      db.runCommand({
+         collMod: "weather24h",
+         timeseries: { granularity: "seconds" || "minutes" || "hours" }
+      })
+
+   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``.
+
+   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
+
+   .. important::
+
+      As with all :ref:`system collections
+      <metadata-system-collections>`, do not run any operations on the
+      underlying ``system.buckets`` collection. 
+
+   .. seealso::
+
+      :ref:`timeseries-granularity`
+
 .. _resize-capped-collection:
 
 Resize a Capped Collection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. versionadded:: 6.0
 
-Starting in MongoDB 6.0, you can resize a capped collection. To change a  
-:ref:`capped collection's <manual-capped-collection>` maximum size in bytes, use
-the ``cappedSize`` option. To change the maximum number of documents in 
-an existing capped collection, use the ``cappedMax`` option.
+Starting in MongoDB 6.0, you can resize a capped collection. To change a
+:ref:`capped collection's <manual-capped-collection>` maximum size in
+bytes, use the ``cappedSize`` option. To change the maximum number of
+documents in an existing capped collection, use the ``cappedMax`` option.
 
 .. note:: 
 
@@ -329,9 +361,13 @@ to 100000 bytes and sets the maximum number of documents in the collection to 50
 Change Streams with Document Pre- and Post-Images
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 6.0
+
+.. collflag:: changeStreamPreAndPostImages
+
 .. include:: /includes/change-stream-pre-and-post-images-introduction.rst
 
-To use :dbcommand:`collMod` to enable change stream pre- and post-images
+To use ``collMod`` to enable change stream pre- and post-images
 for a collection, use the ``changeStreamPreAndPostImages`` field:
 
 .. code-block:: javascript
@@ -368,15 +404,15 @@ Write Concern
 ~~~~~~~~~~~~~
 
 Optional. A document expressing the :doc:`write concern
-</reference/write-concern>` of the :dbcommand:`collMod` command.
+</reference/write-concern>` of the ``collMod`` command.
 
 Omit to use the default write concern.
 
 Access Control
 --------------
 
 If the deployment enforces authentication/authorization, you must have
-the following privilege to run the :dbcommand:`collMod` command:
+the following privilege to run the ``collMod`` command:
 
 .. list-table::
    :header-rows: 1
@@ -580,4 +616,4 @@ entries:
    }
 
 To complete the conversion, modify the duplicate entries to remove any
-conflicts and re-run ``collMod()`` with the ``unique`` option.
+conflicts and re-run ``collMod()`` with the ``unique`` option.