You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ii...@apache.org on 2020/09/21 13:48:00 UTC
[couchdb-documentation] 01/02: Document pagination API
This is an automated email from the ASF dual-hosted git repository.
iilyak pushed a commit to branch pagination
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
commit d0c7dba9775a35897f17584db600171be3dba833
Author: ILYA Khlopotov <ii...@apache.org>
AuthorDate: Mon May 25 07:29:04 2020 -0700
Document pagination API
---
src/api/database/bulk-api.rst | 3 +++
src/api/ddoc/views.rst | 45 +++++++++++++++++++++++++++++++++
src/ddocs/views/pagination.rst | 56 ++++++++++++++++++++++++++++++++++++++++--
3 files changed, 102 insertions(+), 2 deletions(-)
diff --git a/src/api/database/bulk-api.rst b/src/api/database/bulk-api.rst
index 14e72ba..15cc623 100644
--- a/src/api/database/bulk-api.rst
+++ b/src/api/database/bulk-api.rst
@@ -332,6 +332,9 @@ Sending multiple queries to a database
:param db: Database name
+ :query number page_size: Specify the number of queries in the result.
+ Enables paginated reply for included queries.
+
:<header Content-Type: - :mimetype:`application/json`
:<header Accept: - :mimetype:`application/json`
diff --git a/src/api/ddoc/views.rst b/src/api/ddoc/views.rst
index b3876c2..e438b32 100644
--- a/src/api/ddoc/views.rst
+++ b/src/api/ddoc/views.rst
@@ -28,6 +28,7 @@
:<header Accept: - :mimetype:`application/json`
- :mimetype:`text/plain`
+ :query string bookmark: Specify a bookmark to get sepcific page of the results.
:query boolean conflicts: Include `conflicts` information in response.
Ignored if `include_docs` isn't ``true``. Default is ``false``.
:query boolean descending: Return the documents in descending order by key.
@@ -60,6 +61,8 @@
the keys specified in the array.
:query number limit: Limit the number of the returned documents to the
specified number.
+ :query number page_size: Specify the number of rows in the result.
+ Enables paginated reply.
:query boolean reduce: Use the reduction function. Default is ``true`` when
a reduce function is defined.
:query number skip: Skip this number of records before starting to return
@@ -916,3 +919,45 @@ Sending multiple queries to a view
}
]
}
+
+.. _api/ddoc/view/pagination:
+
+Pagination
+==========
+
+.. versionadded:: 4.0
+
+There is a support for token based pagination. The token based pagination is an
+alternative to previously recomended :ref:`pagination recipe <views/pagination>`
+based on ``offset``, ``limit`` and ``skip``.
+
+The user can request paginated mode by setting ``page_size`` query parameter. When
+pagination is enabled the response would include ``next`` and ``previous`` tokens.
+Which can be used to retrieve next and previous page of the results.
+The maximum possible page size is configured via ``request_limits``
+section in one of the ``ini`` files.
+
+.. code-block:: ini
+
+ [request_limits]
+ _all_docs = 5000
+ _all_docs/queries = 5000
+ _all_dbs = 5000
+ _view = 2500
+ _view/queries = 2500
+
+
+Note that ``page_size`` for :ref:`Multiple queries <api/ddoc/view/multiple_queries>`
+endpoints limits number of queries the user can submit in the body of the request.
+
+Compatibility notes
+-------------------
+
+- ``page_size`` is forbidden in the query object passed in ``queries`` array \
+ submitted via :post:`/{db}/_design/{ddoc}/_view/{view}/queries` request.
+
+- ``keys`` propery is incompatible with ``page_size``.
+
+- value for ``skip`` property has to be in range of ``[0..<request_limit>]``.
+
+- ``bookmark`` is incompatible with any other query parameters
diff --git a/src/ddocs/views/pagination.rst b/src/ddocs/views/pagination.rst
index 6cae038..867f66c 100644
--- a/src/ddocs/views/pagination.rst
+++ b/src/ddocs/views/pagination.rst
@@ -123,8 +123,60 @@ Or in a pseudo-JavaScript snippet:
page.display_link('next');
}
-Paging
-======
+
+Paging (New Way)
+================
+
+.. versionadded:: 4.0
+
+To get the first five rows from the view result, you use the ``?page_size=5``
+query parameter::
+
+ curl -X GET http://127.0.0.1:5984/artists/_design/artists/_view/by-name?page_size=5
+
+The result:
+
+.. code-block:: javascript
+
+ {"total_rows":11,"offset":0,"rows":[
+ {"id":"a0746072bba60a62b01209f467ca4fe2","key":"Biffy Clyro","value":null},
+ {"id":"b47d82284969f10cd1b6ea460ad62d00","key":"Foo Fighters","value":null},
+ {"id":"45ccde324611f86ad4932555dea7fce0","key":"Tenacious D","value":null},
+ {"id":"d7ab24bb3489a9010c7d1a2087a4a9e4","key":"Future of the Left","value":null},
+ {"id":"ad2f85ef87f5a9a65db5b3a75a03cd82","key":"Helmet","value":null}
+ ],
+ "next": "an encoded string representing bookmark pointing to next page of results"
+ }
+
+By presence of ``next`` property we can determine if there are more pages to display.
+
+To get next page from CouchDB we would use::
+
+ curl -X GET 'http://127.0.0.1:5984/artists/_design/artists/_view/by-name?bookmark=<the next token>'
+
+The result:
+
+.. code-block:: javascript
+
+ {"total_rows":11,"offset":5,"rows":[
+ {"id":"a2f31cfa68118a6ae9d35444fcb1a3cf","key":"Nirvana","value":null},
+ {"id":"67373171d0f626b811bdc34e92e77901","key":"Kerub","value":null},
+ {"id":"3e1b84630c384f6aef1a5c50a81e4a34","key":"Perfect Circle","value":null},
+ {"id":"84a371a7b8414237fad1b6aaf68cd16a","key":"Queens of the Stone Age",
+ "value":null},
+ {"id":"dcdaf08242a4be7da1a36e25f4f0b022","key":"Silverchair","value":null}
+ ],
+ "previous": "an encoded string representing bookmark pointing to previous page of results",
+ "next": "an encoded string representing bookmark pointing to next page of results",
+ }
+
+The ``previous`` property can be used to get the previous page of the results if need to::
+
+ curl -X GET 'http://127.0.0.1:5984/artists/_design/artists/_view/by-name?bookmark=<the previous token>'
+
+
+Paging (Old Way)
+================
To get the first five rows from the view result, you use the ``?limit=5``
query parameter::