From 77bc0c7b73b6810fe97c3a7c10255b25ebe69027 Mon Sep 17 00:00:00 2001
From: Dan Larkin-York <dan.larkin-york@mongodb.com>
Date: Thu, 27 May 2021 19:13:28 +0000
Subject: SERVER-55118 Architecture Guide updates for PM-2207

---
 src/mongo/db/timeseries/README.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/mongo/db/timeseries/README.md b/src/mongo/db/timeseries/README.md
index 0be14e8d509..559df91856c 100644
--- a/src/mongo/db/timeseries/README.md
+++ b/src/mongo/db/timeseries/README.md
@@ -29,13 +29,13 @@ certain properties:
 
 ```
 {
-    _id: <Object ID with time component equal to first measurement in this bucket>,
+    _id: <Object ID with time component equal to control.min.<time field>>,
     control: {
         // <Some statistics on the measurements such min/max values of data fields>
         version: 1,  // Version of bucket schema. Currently fixed at 1 since this is the
                      // first iteration of time-series collections.
         min: {
-            <time field>: <time of first measurement in this bucket>,
+            <time field>: <time of first measurement in this bucket, rounded down based on granularity>,
             <field0>: <minimum value of 'field0' across all measurements>,
             <field1>: <maximum value of 'field1' across all measurements>,
             ...
@@ -142,6 +142,26 @@ inserted. On subsequent batch commits, we perform an update operation. Instead o
 full document (a so-called "classic" update), we create a DocDiff directly (a "delta" or "v2"
 update).
 
+# Granularity
+
+The `granularity` option for a time-series collection can be set at creation to be 'seconds',
+'minutes' or 'hours'. A later `collMod` operation can change the option from 'seconds' to 'minutes'
+or from 'minutes' to 'hours', but no other transitions are currently allowed. This parameter is
+intended to convey the rough time period between measurements in a given time-series, and is used to
+tweak other internal parameters that affect bucketing.
+
+The maximum span of time that a single bucket is allowed to cover is controlled by `granularity`,
+with the maximum span being set to one hour for 'seconds', 24 hours for 'minutes', and 30 days
+for 'hours'.
+
+When a new bucket is opened by the `BucketCatalog`, the timestamp component of its `_id`, and
+equivalently the value of its `control.min.<time field>`, will be taken from the first measurement
+inserted to the bucket and rounded down based on the `granularity`. It will be rounded down to the
+nearest minute for 'seconds', the nearest hour for 'minutes', and the nearest day for 'hours'. This
+rounding may not be perfect in the case of leap seconds and other irregularities in the calendar,
+and will generally be accomplished by basic modulus aritmetic operating on the number of seconds
+since the epoch, assuming 60 seconds per minute, 60 minutes per hour, and 24 hours per day.
+
 # References
 See:
 [MongoDB Blog: Time Series Data and MongoDB: Part 2 - Schema Design Best Practices](https://www.mongodb.com/blog/post/time-series-data-and-mongodb-part-2-schema-design-best-practices)
-- 
cgit v1.2.1