Primary Index

Summary

The primary index is the fastest way to retrieve data from your database.

API Demo

Enhance this tutorial with live data from a sample database inside your Cloudant account.

For security purposes, please sign in or sign up to demo the API.

API Demo

To demo the Cloudant API, you'll need to replicate a small sample database into your account. The database is named animaldb, and it contains information from Wikipedia about ten different animals.


Retrieving data

The primary index is fast because it comes with every Cloudant database, which means you don't have to write any code before you can use it.

The primary index, often referred to as _all_docs, returns an id, a key and a value for every document in the database. The id and key are the same (Cloudant makes an index keyed by doc id), while the value is the _rev of the document.

_all_docs also reports on the total number of documents and any offset used to query the index.

API DEMO

Demo the Cloudant API right here. The server response (JSON) will appear directly below.

Sign in or create a free account to demo the Cloudant API.

To demo the API here, replicate the sample database first.

Query
https://[username].cloudant.com/animaldb/_all_docs
Test for yourself

Sort order

All indexes are sorted by their key. The sort order is:

  • null
  • false
  • true
  • numbers
  • text, cases sensitive - lower case first
  • arrays, sorted element by element
  • objects

The full specification is documented in the CouchDB Wiki.

API Options

The generic _all_docs request above returns all the documents in the database. That's fine for this example database, but in a realistic scenario you'll probably want a more manageable result set. That's where API options come in.

Limit & skip

Add the limit parameter to keep your result set to a certain size. If you want to offset your result set (for example to paginate through some rows) you can also pass in a skip parameter.

API DEMO

In this call, we limit the result set to 2 rows and skip the first 3 rows.

Query
https://[username].cloudant.com/animaldb/_all_docs?limit=2&skip=3
Test for yourself

Slicing

Use slicing to pull out row ranges from the index by using start and end keys in your query.

API DEMO

Here we are looking for animals with names that begin with letters greater than the startkey up to and including the endkey.

Query
https://[username].cloudant.com/animaldb/_all_docs?startkey="d"&endkey="giraffe"
Test for yourself

If you don't want to include documents that match the end key, add the inclusive_end parameter with a value of false.

Query
https://[username].cloudant.com/animaldb/_all_docs?startkey="d"&endkey="giraffe"&inclusive_end=false
Test for yourself

View slicing with starkey and endkey can be combined with skip, limit and inclusive_end to further constrain your result set.

Query
https://[username].cloudant.com/animaldb/_all_docs?startkey="d"&endkey="llama"&inclusive_end=false&skip=2
Test for yourself

Single key matching

Cloudant's primary index automatically turns a document's _id into its key. If you want a document matching a single key, find it with the key parameter.

API DEMO

Here, we're looking for a document indexed with the key of "llama".

Query
https://[username].cloudant.com/animaldb/_all_docs?key="llama"
Test for yourself

You can also hit the document directly, without additional parameters, at its unique URL. The result is similar to the single key request we made above, but different in that all fields are included in the result.

Query
https://[username].cloudant.com/animaldb/llama
Test for yourself

Retrieving document contents

Use include_docs=true when you want all of the contents of the document you're requesting (not just the id).

API DEMO

This API call uses include_docs=true along with limit and skip.

Query
https://[username].cloudant.com/animaldb/_all_docs?limit=2&skip=3&include_docs=true
Test for yourself

Query by POST

You can also query for a specific set of keys by POSTing a JSON array of keys to the view.

API DEMO

POST data
Query
https://[username].cloudant.com/animaldb/_all_docs
Test for yourself

As we've seen, the _all_docs index can be a very useful view into your database, especially if your application has a natural unique identifier that you can use for your documents.

As your data grows, you'll want to explore secondary indexes, which allow you to build additional indexes over your database, defined by efficient MapReduce views.