Add time-seq and _changes since=time docs

Author: nickva

src/docs/src/api/database/changes.rst

@@ -94,8 +94,15 @@
     :query number limit: Limit number of result rows to the specified value
         (note that using ``0`` here has the same effect as ``1``).
     :query since: Start the results from the change immediately after the given
-        update sequence. Can be valid update sequence or ``now`` value.
-        Default is ``0``.
+        update sequence. Default is ``0``. Other values can be:
+
+        - A valid update sequence, for example, from a ``_changes`` feed response.
+        - ``now``
+        - ``0``
+        - A timestmap string matching the ``YYYY-MM-DDTHH:MM:SSZ``
+          format. The results returned will depend on the time-sequence
+          intervals recorded by the time-seq data structure. To inspect or reset
+          it use the :ref:`_time_seq <api/db/time_seq>` endpoint.
     :query string style: Specifies how many revisions are returned in the
         changes array. The default, ``main_only``, will only return the current
         "winning" revision; ``all_docs`` will return all leaf revisions

src/docs/src/api/database/misc.rst

@@ -568,3 +568,114 @@ following behavior:
         {
             "ok": true
         }
+
+.. _api/db/time_seq:
+
+=====================
+``/{db}/_time_seq``
+=====================
+
+.. http:get:: /{db}/_time_seq
+    :synopsis: Get the time-seq data structure summaries
+
+    Time-seq is a data structure which keeps track of how db sequences map to
+    rough time intervals. Each summary contains all the interval start times
+    and the number of sequences in that time interval.
+
+    :param db: Database name
+    :<header Accept: - :mimetype:`application/json`
+                     - :mimetype:`text/plain`
+    :>header Content-Type: - :mimetype:`application/json`
+                           - :mimetype:`text/plain; charset=utf-8`
+    :>json object time_seq: A time_seq summaries broken down by range and node.
+    :code 200: Request completed successfully
+    :code 400: Invalid database name
+    :code 401: Read privilege required
+    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
+    :code 415: Bad :header:`Content-Type` value
+    :code 500: Internal server error or timeout
+
+    **Request**:
+
+    .. code-block:: http
+
+        GET /db/_time_seq HTTP/1.1
+        Accept: application/json
+        Host: localhost:5984
+
+    **Response**:
+
+    .. code-block:: http
+
+        HTTP/1.1 200 OK
+        Cache-Control: must-revalidate
+        Content-Length: 400
+        Content-Type: application/json
+
+        {
+            "time_seq": {
+                "00000000-7fffffff": {
+                    "[email protected]": [
+                        ["2025-07-27T06:00:00Z", 8],
+                        ["2025-07-27T09:00:00Z", 13],
+                        ["2025-07-27T12:00:00Z", 13],
+                        ["2025-07-27T15:00:00Z", 7],
+                        ["2025-07-27T18:00:00Z", 3]
+                    ]
+                },
+                "80000000-ffffffff": {
+                    "[email protected]": [
+                        ["2025-07-27T03:00:00Z", 1],
+                        ["2025-07-27T06:00:00Z", 10],
+                        ["2025-07-27T09:00:00Z", 5],
+                        ["2025-07-27T12:00:00Z", 5],
+                        ["2025-07-27T15:00:00Z", 11],
+                        ["2025-07-27T18:00:00Z", 2]
+                    ]
+                }
+            }
+        }
+
+.. http:delete:: /{db}/_time_seq
+    :synopsis: Reset time-seq data structures.
+
+    Time-seq is a data structure which keeps track of how db sequences map to
+    rough time intervals. The ``DELETE`` method will reset time-seq data
+    structure for all the shards in the database. Resetting the time-seq
+    structure is always safe and doesn't alter the main b-trees, document
+    revisions, or document bodies. It just resets the time to database
+    sequences mappings. This should be rarely needed and is mainly to be used
+    perhaps in the case when the OS time settings were misconfigured and the
+    the time-seq data structures recorded invalid dates from a distant future.
+
+    :param db: Database name
+    :<header Accept: - :mimetype:`application/json`
+                     - :mimetype:`text/plain`
+    :<header Content-Type: :mimetype:`application/json`
+    :>header Content-Type: - :mimetype:`application/json`
+                           - :mimetype:`text/plain; charset=utf-8`
+    :>json boolean ok: Operation status
+    :code 200: Request completed successfully
+    :code 400: Invalid JSON data
+    :code 401: Unauthorized request to a protected API
+    :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
+
+    **Request**:
+
+    .. code-block:: http
+
+        DELETE /db/_time_seq HTTP/1.1
+        Content-Length: 0
+        Host: localhost:15984
+
+    **Response**:
+
+    .. code-block:: http
+
+        HTTP/1.1 200 OK
+        Content-Length: 12
+        Content-Type: application/json
+
+        {
+            "ok": true
+        }

src/docs/src/config/couchdb.rst

@@ -257,3 +257,22 @@ Base CouchDB Options
 
             [couchdb]
             js_engine = spidermonkey
+
+    .. config:option:: time_seq_min_time :: Minimum time-seq threshold
+
+        .. versionchanged:: 3.6
+
+        Time-seq is the data structure in the database files which keeps track
+        of the mapping between rough time intervals and database sequence
+        numbers. This setting is minimum time threshold below which updates to
+        the time-seq data structure will be ignored. This may be useful, for
+        example, in embedded systems which do not keep their own time when
+        turned off, and instead only rely on NTP synchronization. Such systems
+        after boot may briefly default to some time like 1970-01-01 until they
+        synchronize. The default setting value is some recent time before the
+        latest CouchDB release or before feature was developed. The value may
+        be bumped on future release. The value is expected to be in Unix
+        seconds (see ``wikipedia.org/wiki/inix_time`` for more details) ::
+
+           [couchdb]
+           time_seq_min_time = 1754006400