This is an automated email from the ASF dual-hosted git repository. vatamane pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit aff29aee10b45150811f99cea77bc7c0fd85a952 Author: Nick Vatamaniuc <[email protected]> AuthorDate: Mon Jul 28 02:53:29 2025 -0400 Add time-seq and _changes since=time docs --- src/docs/src/api/database/changes.rst | 11 +++- src/docs/src/api/database/misc.rst | 111 ++++++++++++++++++++++++++++++++++ src/docs/src/config/couchdb.rst | 19 ++++++ 3 files changed, 139 insertions(+), 2 deletions(-) diff --git a/src/docs/src/api/database/changes.rst b/src/docs/src/api/database/changes.rst index b52ee161a..cbf47b6fb 100644 --- a/src/docs/src/api/database/changes.rst +++ b/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 diff --git a/src/docs/src/api/database/misc.rst b/src/docs/src/api/database/misc.rst index 2124d94bc..69c7d467a 100644 --- a/src/docs/src/api/database/misc.rst +++ b/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 + } diff --git a/src/docs/src/config/couchdb.rst b/src/docs/src/config/couchdb.rst index a9f2a2ac6..b07ea5a30 100644 --- a/src/docs/src/config/couchdb.rst +++ b/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/unix_time`` for more details) :: + + [couchdb] + time_seq_min_time = 1754006400
