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:47:59 UTC
[couchdb-documentation] branch pagination created (now e0eae75)
This is an automated email from the ASF dual-hosted git repository.
iilyak pushed a change to branch pagination
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.
at e0eae75 Address problems identified durring review
This branch includes the following new commits:
new d0c7dba Document pagination API
new e0eae75 Address problems identified durring review
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[couchdb-documentation] 01/02: Document pagination API
Posted by ii...@apache.org.
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::
[couchdb-documentation] 02/02: Address problems identified durring
review
Posted by ii...@apache.org.
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 e0eae75fe698148e75c3a50c6e2b245621d7d86e
Author: ILYA Khlopotov <ii...@apache.org>
AuthorDate: Mon Sep 21 06:47:19 2020 -0700
Address problems identified durring review
---
src/api/database/bulk-api.rst | 2 +-
src/api/ddoc/views.rst | 13 ++++++-------
src/ddocs/views/pagination.rst | 24 +++++++++++-------------
3 files changed, 18 insertions(+), 21 deletions(-)
diff --git a/src/api/database/bulk-api.rst b/src/api/database/bulk-api.rst
index 15cc623..4f2af0f 100644
--- a/src/api/database/bulk-api.rst
+++ b/src/api/database/bulk-api.rst
@@ -332,7 +332,7 @@ Sending multiple queries to a database
:param db: Database name
- :query number page_size: Specify the number of queries in the result.
+ :query number page_size: The number of queries in the result.
Enables paginated reply for included queries.
:<header Content-Type: - :mimetype:`application/json`
diff --git a/src/api/ddoc/views.rst b/src/api/ddoc/views.rst
index e438b32..4347962 100644
--- a/src/api/ddoc/views.rst
+++ b/src/api/ddoc/views.rst
@@ -28,7 +28,7 @@
:<header Accept: - :mimetype:`application/json`
- :mimetype:`text/plain`
- :query string bookmark: Specify a bookmark to get sepcific page of the results.
+ :query string bookmark: 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.
@@ -61,7 +61,7 @@
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.
+ :query number page_size: 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.
@@ -927,8 +927,8 @@ 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>`
+CouchDB supports token-based pagination, which is an alternative to
+:ref:`pagination recipe <views/pagination>`
based on ``offset``, ``limit`` and ``skip``.
The user can request paginated mode by setting ``page_size`` query parameter. When
@@ -946,7 +946,6 @@ section in one of the ``ini`` files.
_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.
@@ -956,8 +955,8 @@ 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``.
+- The ``keys`` propery is incompatible with ``page_size``.
-- value for ``skip`` property has to be in range of ``[0..<request_limit>]``.
+- value for ``skip`` property must 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 867f66c..bf5a736 100644
--- a/src/ddocs/views/pagination.rst
+++ b/src/ddocs/views/pagination.rst
@@ -123,9 +123,8 @@ Or in a pseudo-JavaScript snippet:
page.display_link('next');
}
-
-Paging (New Way)
-================
+`page_size` based paging (recommended)
+======================================
.. versionadded:: 4.0
@@ -134,7 +133,7 @@ query parameter::
curl -X GET http://127.0.0.1:5984/artists/_design/artists/_view/by-name?page_size=5
-The result:
+The result::
.. code-block:: javascript
@@ -148,13 +147,13 @@ The result:
"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.
+By presence of ``next`` property we can determine if there are more pages to display.
-To get next page from CouchDB we would use::
+To get the 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:
+The result::
.. code-block:: javascript
@@ -170,13 +169,12 @@ The result:
"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::
+Likewise, the ``previous`` property can be used to get the previous page of the results::
curl -X GET 'http://127.0.0.1:5984/artists/_design/artists/_view/by-name?bookmark=<the previous token>'
-
-Paging (Old Way)
-================
+Skip based paging
+=================
To get the first five rows from the view result, you use the ``?limit=5``
query parameter::
@@ -243,8 +241,8 @@ straightforward:
return page != last_page;
}
-Paging (Alternate Method)
-=========================
+`startkey` based paging
+=======================
The method described above performed poorly with large skip values until
CouchDB 1.2. Additionally, some use cases may call for the following