{"id":1755,"date":"2014-12-16T18:49:28","date_gmt":"2014-12-16T18:49:27","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=1755"},"modified":"2025-06-13T23:51:53","modified_gmt":"2025-06-14T06:51:53","slug":"pagination-couchbase","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/pagination-couchbase\/","title":{"rendered":"Pagination Best Practices with Couchbase"},"content":{"rendered":"

[This blog was syndicated from https:\/\/blog.grallandco.com]<\/em><\/p>\n

<\/div>\n

If you have to deal with a large number of documents when doing queries against a Couchbase cluster it is important to use pagination to get rows by page. You can find some information in the documentation in the chapter “Pagination<\/a>“, but I want to go in more details and sample code in this article.
\nFor this pagination example I will start by creating a simple view based on the <\/span>beer-sample<\/span> dataset, the view is used to find brewery by country:<\/span><\/p>\n

\n
function (doc, meta) {
\nif (doc.type == “brewery” && doc.country){
\nemit(doc.country);
\n}
\n}<\/div>\n<\/div>\n

 <\/p>\n

This view list all the breweries by country, the index looks like:<\/p>\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Doc id<\/th>\nKey<\/th>\nValue<\/th>\n<\/tr>\n
bersaglier<\/td>\nArgentina<\/td>\nnull<\/td>\n<\/tr>\n
cervecera_jerome<\/td>\nArgentina<\/td>\nnull<\/td>\n<\/tr>\n
brouwerij_nacional_balashi<\/td>\nAruba<\/td>\nnull<\/td>\n<\/tr>\n
australian_brewing_corporation<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
carlton_and_united_breweries<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
coopers_brewery<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
foster_s_australia_ltd<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
gold_coast_brewery<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
lion_nathan_australia_hunter_street<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
little_creatures_brewery<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
malt_shovel_brewery<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
matilda_bay_brewing<\/td>\nAustralia<\/td>\nnull<\/td>\n<\/tr>\n
…<\/td>\n…<\/td>\n…<\/td>\n<\/tr>\n
…<\/td>\n…<\/td>\n…<\/td>\n<\/tr>\n
…<\/td>\n…<\/td>\n…<\/td>\n<\/tr>\n
yellowstone_valley_brewing<\/td>\nUnited States<\/td>\nnull<\/td>\n<\/tr>\n
yuengling_son_brewing<\/td>\nUnited States<\/td>\nnull<\/td>\n<\/tr>\n
zea_rotisserie_and_brewery<\/td>\nUnited States<\/td>\nnull<\/td>\n<\/tr>\n
fosters_tien_gang<\/td>\nViet Nam<\/td>\nnull<\/td>\n<\/tr>\n
hue_brewery<\/td>\nViet Nam<\/td>\nnull<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n

So now you want to navigate in this index with a page size of 5 rows.<\/span><\/p>\n

Using skip \/ limit Parameters<\/h3>\n

The most simplistic approach is to use limit<\/span> and skip<\/span> parameters for example:<\/p>\n

Page 1 : \u00a0?limit=5&skip0<\/span>
\nPage 2: \u00a0 ?limit=5&skip=5<\/span>
\n…
\nPage x: \u00a0 ?limit=5&skip(limit*(page-1))<\/span><\/p>\n

You can obviously use any other parameters you need to do range or key queries (startkey\/endkey, key, keys<\/span>) and sort option (descending<\/span>).<\/p>\n

This is simple but not the most efficient way, since the query engine has to read all the rows that match the query, until the skip value is reached.<\/p>\n

Some code sample in python that paginate using this view :<\/p>\n

This application loops on all the pages until the end of the index.<\/p>\n

As I said before this does not represent pagination best practices since the system must read all the values until the skip is reached. The following example shows a better way to deal with this.<\/p>\n

Using startkey \/ startkey_docid parameters<\/h3>\n
To make this pagination more efficient it is possible to take another approach. This approach uses the startkey<\/span>\u00a0and startkey_docid<\/span> \u00a0to select the proper documents.<\/div>\n
\n