Update pagination docs - COUCHDB-1076 is old now As far as I'm aware, skip is equivalently fast to a startkey search because whole subtrees are skipped when their document count does not exceed the remaining skip.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/8d37ee36 Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/8d37ee36 Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/8d37ee36 Branch: refs/heads/2041-update-ibrowse Commit: 8d37ee36f23e5aea09f1fd17fd783b74a45d2e7e Parents: adf9ae2 Author: Randall Leeds <[email protected]> Authored: Sun Mar 9 20:40:55 2014 -0700 Committer: Randall Leeds <[email protected]> Committed: Sun Mar 9 20:43:37 2014 -0700 ---------------------------------------------------------------------- share/doc/src/couchapp/views/pagination.rst | 48 ++++++++---------------- 1 file changed, 15 insertions(+), 33 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/8d37ee36/share/doc/src/couchapp/views/pagination.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/couchapp/views/pagination.rst b/share/doc/src/couchapp/views/pagination.rst index b40f988..6f3b34e 100644 --- a/share/doc/src/couchapp/views/pagination.rst +++ b/share/doc/src/couchapp/views/pagination.rst @@ -125,12 +125,11 @@ Or in a pseudo-JavaScript snippet: page.display_link('next'); } -Slow Paging (Do Not Use) -======================== +Paging +====== -**Donât use this method!** We just show it because it might seem natural to use, -and you need to know why it is a bad idea. To get the first five rows from -the view result, you use the ``?limit=5`` query parameter:: +To get the first five rows from the view result, you use the ``?limit=5`` +query parameter:: curl -X GET http://127.0.0.1:5984/artists/_design/artists/_view/by-name?limit=5 @@ -194,34 +193,17 @@ straightforward: return page != last_page; } -The dealbreaker ---------------- - -This all looks easy and straightforward, but it has one fatal flaw. Remember -how view results are generated from the underlying B-tree index: CouchDB -jumps to the first row (or the first row that matches ``startkey``, -if provided) and reads one row after the other from the index until there are -no more rows (or ``limit`` or ``endkey`` match, if provided). - -The ``skip`` argument works like this: in addition to going to the first row and -starting to read, skip will skip as many rows as specified, but CouchDB will -still read from the first row; it just wonât return any values for the skipped -rows. If you specify ``skip=100``, CouchDB will read 100 rows and not create -output for them. This doesnât sound too bad, but it is very bad, when you use -1000 or even 10000 as skip values. CouchDB will have to look at a lot of rows -unnecessarily. - -As a rule of thumb, skip should be used only with single digit values. While -itâs possible that there are legitimate use cases where you specify a larger -value, they are a good indicator for potential problems with your solution. -Finally, for the calculations to work, you need to add a reduce function and -make two calls to the view per page to get all the numbering right, -and thereâs still a potential for error. - -Fast Paging (Do Use) -==================== - -The correct solution is not much harder. Instead of slicing the result set +Paging (Alternate Method) +========================= + +The method described above performed poorly with large skip values until +CouchDB 1.2. Additionally, some use cases may call for the following +alternate method even with newer versions of CouchDB. One such case is when +duplicate results should be prevented. Using skip alone it is possible for +new documents to be inserted during pagination which could change the offset +of the start of the subsequent page. + +A correct solution is not much harder. Instead of slicing the result set into equally sized pages, we look at 10 rows at a time and use ``startkey`` to jump to the next 10 rows. We even use skip, but only with the value 1.
