Writing and Querying MapReduce Views in CouchDB

Limiting, Skipping, and Reversing Results

CouchDB allows you to limit the number of results returned, skip an arbitrary number of results, and reverse the output of results to be in descending order.

Limit

Let’s query for all book formats, but limit the number of results to five:

curl -X GET http://localhost:5984/books/_design/default/_view/formats -G \
-d reduce=false \
-d limit=5

The response:

{
   "total_rows":7,
   "offset":0,
   "rows":[
      {
         "id":"978-0-596-15589-6",
         "key":"Ebook",
         "value":272
      },
      {
         "id":"978-0-596-52926-0",
         "key":"Ebook",
         "value":448
      },
      {
         "id":"978-0-596-15589-6",
         "key":"Print",
         "value":272
      },
      {
         "id":"978-0-596-52926-0",
         "key":"Print",
         "value":448
      },
      {
         "id":"978-1-565-92580-9",
         "key":"Print",
         "value":648
      }
   ]
}

See Table 4-6 for the rows in tabular format.

Table 4-6. Rows from the formats view, limited to five

key	id	value
"Ebook"	"978-0-596-15589-6"	272
"Ebook"	"978-0-596-52926-0"	448
"Print"	"978-0-596-15589-6"	272
"Print"	"978-0-596-52926-0"	448
"Print"	"978-1-565-92580-9"	648

Skip

Let’s query for all book formats, limit the number of results to five again, but this time let’s skip the first five results:

curl -X GET http://localhost:5984/books/_design/default/_view/formats -G \
-d reduce=false \
-d limit=5 \
-d skip=5

The response:

{
   "total_rows":7,
   "offset":5,
   "rows":[
      {
         "id":"978-0-596-15589-6",
         "key":"Safari Books Online",
         "value":272
      },
      {
         "id":"978-0-596-52926-0",
         "key":"Safari Books Online",
         "value":448
      }
   ]
}

See Table 4-7 for the rows in tabular format.

Table 4-7. Rows from the formats view, limited to five and skipping the first five results

key	id	value
"Safari Books Online"	"978-0-596-15589-6"	272
"Safari Books Online"	"978-0-596-52926-0"	448

Warning

The skip parameter can be used along with the limit parameter to implement pagination. However, skipping a large number of rows can be inefficient. Instead, set the skip parameter’s value to 1 and use the key of the last row on the previous page as the startkey (endkey if output is reversed) parameter, and the document ID of the last row on the previous page as the startkey_docid (endkey_docid if output is reversed) parameter. This should give you better performance since CouchDB will not need to scan the entire range of skipped rows.

Following best practices, let’s instead set the skip parameter’s value to 1 and use the startkey and startkey_docid parameters:

curl -X GET http://localhost:5984/books/_design/default/_view/formats -G \
-d reduce=false \
-d limit=5 \
-d skip=1 \
--data-urlencode startkey=\
'"Print"' \
--data-urlencode startkey_docid=\
'978-1-565-92580-9' \
-d limit=5

The response:

{
   "total_rows":7,
   "offset":5,
   "rows":[
      {
         "id":"978-0-596-15589-6",
         "key":"Safari Books Online",
         "value":272
      },
      {
         "id":"978-0-596-52926-0",
         "key":"Safari Books Online",
         "value":448
      }
   ]
}

See Table 4-8 for the rows in tabular format.

Table 4-8. Rows from the formats view, limited to five and filtered by start key and document ID

key	id	value
"Safari Books Online"	"978-0-596-15589-6"	272
"Safari Books Online"	"978-0-596-52926-0"	448

Reversing Output

Let’s reverse the output of our book titles view:

curl -X GET http://localhost:5984/books/_design/default/_view/titles -G \
-d reduce=false \
-d descending=true

The response:

{
   "total_rows":3,
   "offset":0,
   "rows":[
      {
         "id":"978-0-596-52926-0",
         "key":"RESTful Web Services",
         "value":448
      },
      {
         "id":"978-1-565-92580-9",
         "key":"DocBook: The Definitive Guide",
         "value":648
      },
      {
         "id":"978-0-596-15589-6",
         "key":"CouchDB: The Definitive Guide",
         "value":272
      }
   ]
}

See Table 4-9 for the rows in tabular format.

Table 4-9. Rows from the titles view in descending order

key	id	value
"RESTful Web Services"	"978-0-596-52926-0"	448
"DocBook: The Definitive Guide"	"978-1-565-92580-9"	648
"CouchDB: The Definitive Guide"	"978-0-596-15589-6"	272

Warning

If you set the descending parameter’s value to true, you will likely have to swap your startkey/startkey_docid and/or endkey/endkey_docid parameter values, if used. This is because the output is reversed before rows are filtered.