flimzy commented on a change in pull request #550:
URL:
https://github.com/apache/couchdb-documentation/pull/550#discussion_r469056448
##########
File path: 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.
Review comment:
For consistency with the other descriptions, I wouldn't make this a
complete sentence.
```suggestion
:query number page_size: The number of queries in the result.
```
##########
File path: 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.
Review comment:
```suggestion
:query string bookmark: A bookmark to get sepcific page of the results.
```
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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.
Review comment:
```suggestion
The user can request paginated mode by setting the ``page_size`` query
parameter. When
pagination is enabled, the response will include ``next`` and ``previous``
tokens,
which can be used to retrieve the next and previous pages of results,
respectively.
```
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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
Review comment:
[Stylistic] Avoid passive voice, and combine sentences to reduce
repetitiveness.
```suggestion
CouchDB supports token-based pagination, which is an
```
##########
File path: 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:
Review comment:
```suggestion
The result::
```
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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.
Review comment:
```suggestion
endpoints limits the number of queries the user can submit in the body of
the request.
```
##########
File path: 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::
Review comment:
```suggestion
Likewise, the ``previous`` property can be used to get the previous page of
the results::
```
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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.
Review comment:
How is the `page_size` limit related to the maximum queries a user can
submit? Is it a 1:1 relationship? (i.e. page_size=2 means 2 queries?)
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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``.
Review comment:
```suggestion
- The ``keys`` property is incompatible with ``page_size``.
```
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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``
Review comment:
The above description indicates that "page_size" controls the maximum
possible page size, so I gather this means something else. Is this referring to
the maximum number of pages? If so, I suggest rewording to make that more
clear:
```suggestion
The maximum number of pages is configured via ``request_limits``
```
If it's something else, can you clarify?
##########
File path: 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::
Review comment:
```suggestion
To get the next page from CouchDB we would use::
```
##########
File path: src/api/ddoc/views.rst
##########
@@ -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.
Review comment:
```suggestion
:query number page_size: The number of rows in the result.
```
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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>`
Review comment:
[Stylistic] Whether it was a previous recommendation probably isn't
relevant here. Might be good detail in a changelog, though.
```suggestion
alternative to :ref:`pagination recipe <views/pagination>`
```
##########
File path: src/ddocs/views/pagination.rst
##########
@@ -123,8 +123,60 @@ Or in a pseudo-JavaScript snippet:
page.display_link('next');
}
-Paging
-======
+
+Paging (New Way)
Review comment:
Could we give these proper names, rather than simply "old" vs "new"?
Perhaps the old way could be called "View-based Paging" for example?
##########
File path: src/api/ddoc/views.rst
##########
@@ -914,3 +917,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>]``.
Review comment:
[Stylistic]
```suggestion
- value for ``skip`` property must be in range of ``[0..<request_limit>]``.
```
##########
File path: 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.
Review comment:
```suggestion
By presence of ``next`` property we can determine if there are more pages to
display.
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
