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-documentation/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/8530c6bb Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/8530c6bb Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/8530c6bb Branch: refs/heads/import-master Commit: 8530c6bbfc89a9017d13e328d0062f6ff55df1cc Parents: 512da7a Author: Randall Leeds <rand...@apache.org> Authored: Sun Mar 9 20:40:55 2014 -0700 Committer: Randall Leeds <rand...@apache.org> Committed: Sun Mar 9 20:43:37 2014 -0700 ---------------------------------------------------------------------- src/couchapp/views/pagination.rst | 48 +++++++++++----------------------- 1 file changed, 15 insertions(+), 33 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/8530c6bb/src/couchapp/views/pagination.rst ---------------------------------------------------------------------- diff --git a/src/couchapp/views/pagination.rst b/src/couchapp/views/pagination.rst index b40f988..6f3b34e 100644 --- a/src/couchapp/views/pagination.rst +++ b/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.
