couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [05/50] documentation commit: updated refs/heads/import-master to fe7f7bf
Date Thu, 10 Jul 2014 09:47:04 GMT
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.


Branch: refs/heads/import-master
Commit: 858a09b2cde29122f712fb321765b2e67f46d7f1
Parents: eece8df
Author: Randall Leeds <>
Authored: Sun Mar 9 20:40:55 2014 -0700
Committer: Randall Leeds <>
Committed: Sun Mar 9 20:43:37 2014 -0700

 src/couchapp/views/pagination.rst | 48 +++++++++++-----------------------
 1 file changed, 15 insertions(+), 33 deletions(-)
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:
-Slow Paging (Do Not Use)
-**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
@@ -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
-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.

View raw message