From c121cb705c8d9dfc223050651e30c32a1ba838ab Mon Sep 17 00:00:00 2001
From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Date: Mon, 12 Jul 2021 22:03:54 +0200
Subject: [PATCH] Clarify granularity

---
 source/core/timeseries-collections.txt        | 24 +++++++++---
 .../timeseries/timeseries-granularity.txt     | 38 ++++++++++++++++++-
 2 files changed, 55 insertions(+), 7 deletions(-)

diff --git a/source/core/timeseries-collections.txt b/source/core/timeseries-collections.txt
index cc5b182c7e3..577350cc7c6 100644
--- a/source/core/timeseries-collections.txt
+++ b/source/core/timeseries-collections.txt
@@ -95,12 +95,24 @@ When creating a time series collection, specify the following options:
 
     - string
 
-    - Optional. Possible values are ``"seconds"`` (default),
-      ``"minutes"``, and ``"hours"``. Set the granularity to the value
-      that is the closest match to the time span between consecutive
-      incoming measurements. Setting the ``granularity`` parameter
-      accurately improves performance by optimizing how data in the time
-      series collection is stored internally.
+    - 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.
 
   * - ``expireAfterSeconds``
 
diff --git a/source/core/timeseries/timeseries-granularity.txt b/source/core/timeseries/timeseries-granularity.txt
index 39ba9abc267..ab731b17b94 100644
--- a/source/core/timeseries/timeseries-granularity.txt
+++ b/source/core/timeseries/timeseries-granularity.txt
@@ -25,7 +25,8 @@ Set Granularity for Time Series Data
 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:
+measurements that have the same unique value for the ``metaField``
+field:
 
 .. code-block:: javascript
 
@@ -44,6 +45,41 @@ measurements:
 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
+
+
 .. seealso::
 
    :ref:`Timing of Automatic Removal