You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by va...@apache.org on 2024/01/05 18:31:56 UTC
(couchdb) 01/01: Improve changes feed API documentation
This is an automated email from the ASF dual-hosted git repository.
vatamane pushed a commit to branch documentation-changes-filter-include-doc
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 45c85676e92b14121d26408a8b0990ce6c8cdfbe
Author: Nick Vatamaniuc <va...@gmail.com>
AuthorDate: Fri Jan 5 13:17:57 2024 -0500
Improve changes feed API documentation
* Remove redundant mention of `_changes resource` since it's already
describing that resource.
* Explicitly enumerate all `filter` parameter options with references to doc
section below for each.
* Explain the unexpected interaction between ``include_docs``, ``all_docs``
style and filtering, how the winning document body is returned even if it
doesn't pass the filtering criteria.
* Update `POST _changes` doc to say that besides `doc_ids` it is used for
selector filtering. Also, add an example of using a selector.
---
src/docs/src/api/database/changes.rst | 101 ++++++++++++++++++++++++++++------
1 file changed, 83 insertions(+), 18 deletions(-)
diff --git a/src/docs/src/api/database/changes.rst b/src/docs/src/api/database/changes.rst
index ed4657bca..745a0e5c5 100644
--- a/src/docs/src/api/database/changes.rst
+++ b/src/docs/src/api/database/changes.rst
@@ -20,11 +20,10 @@
:synopsis: Returns changes for the given database
Returns a sorted list of changes made to documents in the database, in time
- order of application, can be obtained from the database's ``_changes``
- resource. Only the most recent change for a given document is guaranteed to
- be provided, for example if a document has had fields added, and then
- deleted, an API client checking for changes will not necessarily receive
- the intermediate state of added documents.
+ order of application. Only the most recent change for a given document is
+ guaranteed to be provided, for example if a document has had fields added,
+ and then deleted, an API client checking for changes will not necessarily
+ receive the intermediate state of added documents.
This can be used to listen for update and modifications to the database for
post processing or synchronization, and for practical purposes,
@@ -60,10 +59,17 @@
<changes/eventsource>`. Works the same as Continuous
Mode, but sends the events in `EventSource
<http://dev.w3.org/html5/eventsource/>`_ format.
- :query string filter: Reference to a :ref:`filter function <filterfun>`
- from a design document that will filter whole stream emitting only
- filtered events. See the section `Change Notifications in the book
- CouchDB The Definitive Guide`_ for more information.
+ :query string filter: - **design_doc/filter_name** Reference to a
+ :ref:`filter function <filterfun>` from a design
+ document that will filter whole stream emitting
+ only filtered events. See the section `Change
+ Notifications in the book CouchDB The Definitive
+ Guide`_ for more information.
+ - **_doc_ids** :ref:`doc_ids filter
+ <changes/filter/doc_ids>`
+ - **_view** :ref:`view filter <changes/filter/view>`
+ - **_design** :ref:`design filter
+ <changes/filter/design>`
:query number heartbeat: Period in *milliseconds* after which an empty
line is sent in the results. Only applicable for :ref:`longpoll
<changes/longpoll>`, :ref:`continuous <changes/continuous>`, and
@@ -72,7 +78,10 @@
``true`` to use default value.
:query boolean include_docs: Include the associated document with each
result. If there are conflicts, only the winning revision is returned.
- Default is ``false``.
+ Default is ``false``. When used with ``all_docs`` style and a filter,
+ return the document body even if does not pass the filtering criteria.
+ In other words, filtering applies only to the list of ``"changes"``
+ revision list not the returned document body in the ``"doc"`` field.
:query boolean attachments: Include the Base64-encoded content of
:ref:`attachments <api/doc/attachments>` in the documents that
are included if ``include_docs`` is ``true``. Ignored if ``include_docs``
@@ -87,10 +96,16 @@
: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``.
- :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 (including conflicts and deleted former conflicts).
+ :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
+ (including conflicts and deleted former conflicts). When using a filter
+ with ``all_docs`` style, if none of the revisions match the filter, the
+ changes row is skipped. If at least one revision matches, the changes
+ row is returned with all matching revision. If ``all_docs`` style is
+ used with ``include_docs=true`` and at least one revision matches the
+ filter, the winning doc body is returned, even if it doesn't not pass
+ the filtering criteria.
:query number timeout: Maximum period in *milliseconds* to wait for a change
before the response is sent, even if there are no results.
Only applicable for :ref:`longpoll <changes/longpoll>` or
@@ -228,11 +243,16 @@
.. http:post:: /{db}/_changes
:synopsis: Returns changes for the given database for certain document IDs
+ or selector filter.
+
+ Requests the database changes feed in the same way as :get:`/{db}/_changes`
+ does, but is widely used with ``?filter=_doc_ids`` or ``?filter=_selector``
+ query parameters and allows one to pass a larger list of document IDs or
+ the body of the selector to filter.
- Requests the database changes feed in the same way as
- :get:`/{db}/_changes` does, but is widely used with
- ``?filter=_doc_ids`` query parameter and allows one to pass a larger list of
- document IDs to filter.
+ :param db: Database name
+ :query string filter: - **_doc_ids** :ref:`doc_ids filter <changes/filter/doc_ids>`
+ - **_selector** :ref:`selector filter <changes/filter/selector>`
**Request**:
@@ -278,6 +298,51 @@
]
}
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_changes?filter=_selector HTTP/1.1
+ Accept: application/json
+ Accept-Encoding: gzip, deflate
+ Content-Length: 25
+ Content-Type: application/json
+ Host: 127.0.0.1:5984
+
+ {
+ "selector": {
+ "data": 1
+ }
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Fri, 05 Jan 2024 18:08:46 GMT
+ ETag: "9UTJJV90GMV3XQKBM9RNAS0IK"
+ Server: CouchDB/3.3.3-42c2484 (Erlang OTP/24)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": "4-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE5lzgQLshqkGSWmGyZjKcRqRxwIkGRqA1H-oSYxgk0ySLSxSEi0wdWUBAGlCJKQ",
+ "pending": 0,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "3-fc9d7a5cf38c9f062aa246cb072eae68"
+ }
+ ],
+ "id": "d1",
+ "seq": "4-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE5lzgQLshqkGSWmGyZjKcRqRxwIkGRqA1H-oSYxgk0ySLSxSEi0wdWUBAGlCJKQ"
+ }
+ ]
+ }
+
.. _changes:
Changes Feeds