updates per Arun's feedback

Author: jeff-allen-mongo

source/core/timeseries-collections.txt

@@ -97,44 +97,19 @@ When creating a time series collection, specify the following options:
 
     - string
 
-    - Required. The name of the field which contains the date in each
-      time series document. Documents in a time series collection must
-      have a valid BSON date as the value for the ``timeField``.
+    - .. include:: /includes/time-series/fact-time-field-description.rst
 
   * - ``timeseries.metaField``
 
     - string
 
-    - Optional. The name of the field which contains metadata in each
-      time series document. The metadata in the specified field should
-      be data that is used to label a unique series of documents. The
-      metadata should rarely, if ever, change.
-
-      The name of the specified field may not be ``_id`` or the same as
-      the ``timeseries.timeField``. The field can be of any type.
+    - .. include:: /includes/time-series/fact-meta-field-description.rst
 
   * - ``timeseries.granularity``
 
     - string
 
-    - Optional. Possible values are ``"seconds"``, ``"minutes"``, and
-      ``"hours"``. By default, MongoDB sets the ``granularity`` to
-      ``"seconds"`` for high-frequency ingestion.
-
-      Manually set the ``granularity`` parameter to improve performance
-      by optimizing how data in the time series collection is stored
-      internally. To select a value for ``granularity``, choose the
-      closest match to the time span between consecutive incoming
-      measurements.
-
-      If you specify the ``timeseries.metaField``, consider the time
-      span between consecutive incoming measurements that have the same
-      unique value for the ``metaField`` field. Measurements often have
-      the same unique value for the ``metaField`` field if they come
-      from the same source.
-
-      If you do not specify ``timeseries.metaField``, consider the time
-      span between all measurements that are inserted in the collection.
+    - .. include:: /includes/time-series/fact-granularity-description.rst
 
   * - ``expireAfterSeconds``
 

source/core/timeseries/timeseries-limitations.txt

@@ -132,8 +132,15 @@ Sharding
 ~~~~~~~~
 
 Starting in MongoDB 5.1, sharded time series collections are supported.
+When using sharded time series collections, you cannot:
 
-You cannot modify the ``granularity`` of a sharded time series collection.
+- Modify the ``granularity`` of a sharded time series
+  collection.
+
+- Run sharding administration commands, including:
+
+  - :dbcommand:`moveChunk`
+  - :dbcommand:`splitChunk`
 
 Aggregation $out and $merge
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/includes/5.1/5.1-release-notes-sharded-time-series.rst

@@ -1,3 +1,7 @@
 MongoDB 5.1 provides support for sharded :ref:`time series collections
-<manual-timeseries-collection>`. See :ref:`Time Series Limitations
-<time-series-limitations-sharding>`.
+<manual-timeseries-collection>`.
+
+See:
+
+- :dbcommand:`shardCollection`
+- :ref:`Time Series Limitations <time-series-limitations-sharding>`

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

@@ -0,0 +1,23 @@
+Optional. Possible values are:
+
+- ``"seconds"``
+- ``"minutes"``
+- ``"hours"``
+
+By default, MongoDB sets the ``granularity`` to ``"seconds"`` for
+high-frequency ingestion.
+
+Manually set the ``granularity`` parameter to improve performance
+by optimizing how data in the time series collection is stored
+internally. To select a value for ``granularity``, choose the
+closest match to the time span between consecutive incoming
+measurements.
+
+If you specify the ``timeseries.metaField``, consider the time
+span between consecutive incoming measurements that have the same
+unique value for the ``metaField`` field. Measurements often have
+the same unique value for the ``metaField`` field if they come
+from the same source.
+
+If you do not specify ``timeseries.metaField``, consider the time
+span between all measurements that are inserted in the collection.

source/includes/time-series/fact-meta-field-description.rst

@@ -0,0 +1,7 @@
+Optional. The name of the field which contains metadata in each
+time series document. The metadata in the specified field should
+be data that is used to label a unique series of documents. The
+metadata should rarely, if ever, change.
+
+The name of the specified field may not be ``_id`` or the same as
+the ``timeseries.timeField``. The field can be of any type.

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

@@ -0,0 +1,3 @@
+Required. The name of the field which contains the date in each
+time series document. Documents in a time series collection must
+have a valid BSON date as the value for the ``timeField``.

source/reference/command/shardCollection.txt

@@ -35,7 +35,8 @@ Definition
          unique: <boolean>,
          numInitialChunks: <integer>,
          presplitHashedZones: <boolean>,
-         collation: { locale: "simple" }
+         collation: { locale: "simple" },
+         timeseries: <object>
       }
 
    :dbcommand:`shardCollection` has the following fields:
@@ -170,6 +171,64 @@ Definition
 
           .. versionadded:: 4.4
 
+      * - :ref:`timeseries <cmd-shard-collection-timeseries>`
+
+        - object
+
+        - .. _cmd-shard-collection-presplitHashedZones:
+
+          Optional. Specify this option to create a new sharded
+          :ref:`time series collection <manual-timeseries-collection>`.
+
+          To shard an existing time series collection, omit this
+          parameter. When you omit this parameter and specify a time
+          series collection in the ``shardCollection`` parameter,
+          MongoDB automatically uses the values from the time series
+          collection as the values for the ``timeseries`` field.
+          
+          For detailed syntax, see
+          :ref:`sharded-time-series-collection-options`.
+
+          .. versionadded:: 5.1
+
+.. _sharded-time-series-collection-options:
+
+Time Series Options
+~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.1
+
+Specify the :ref:`timeseries <cmd-shard-collection-timeseries>` option
+to :dbcommand:`shardCollection` to create a new sharded
+:ref:`time series collection <manual-timeseries-collection>`.
+
+The :ref:`timeseries <cmd-shard-collection-timeseries>` option takes
+the following fields:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+
+   * - Field
+     - Type
+     - Description
+
+   * - ``timeField``
+     - string
+     - .. include:: /includes/time-series/fact-time-field-description.rst
+
+   * - ``metaField``
+     - string
+     - .. include:: /includes/time-series/fact-meta-field-description.rst
+
+   * - ``granularity``
+     - string
+     - .. include:: /includes/time-series/fact-granularity-description.rst
+
+   * - ``bucketMaxSpanSeconds``
+     - integer
+     - Optional. The maximum range of time values for a bucket,
+       in seconds.
 
 Considerations
 --------------
@@ -194,6 +253,20 @@ avoid scalability and perfomance issues.
   - :ref:`sharding-shard-key-selection`
   - :ref:`sharding-shard-key`
 
+Shard Keys on Time Series Collections
+`````````````````````````````````````
+
+When sharding time series collections, you can only specify the
+``metaField``, ``timeField``, or both in the shard key. No other fields,
+including ``_id``, are allowed in the shard key pattern.
+
+- ``metaField`` can be either a :ref:`hashed shard key
+  <sharding-hashed-sharding>` or a :ref:`ranged shard key
+  <sharding-ranged>`.
+
+- ``timeField`` can only be a :ref:`ranged shard key
+  <sharding-ranged>`.
+
 .. _hashed-shard-keys:
 
 Hashed Shard Keys
@@ -274,6 +347,7 @@ in the ``records`` database and uses the ``zipcode`` field as the
 .. code-block:: javascript
 
    db.adminCommand( { shardCollection: "records.people", key: { zipcode: 1 } } )
+   
 
 .. seealso::