Using the Primary Index

If you do not already have the IBM Cloudant service provisioned in Bluemix, follow these steps to provision the service. ▼More

---

1. Visit IBM Bluemix at http://console.ng.bluemix.net.
2. If you don't have a Bluemix account, click Sign Up. Complete the fields on the form, and click Create Account.
3. If you have a Bluemix account, click Log In. Provide your IBMid and password, and click Log In.
4. In the top navigation bar, click Catalog.
5. In the left navigator, under Services, check Data and Analytics.
6. Click Cloudant NOSQL DB.
7. Accept the default service, or provide a different name, and click Create. This brings you to the IBM Cloudant Bluemix Service Launch Page.
8. Click Service Credentials. Note your username, password, and host name. You will be able to use the URL (which also passes your username and password) to access your database from a browser.
9. Paste the value for your username here:
10. Click this button to update the URLs for the rest of this tutorial.
11. Click Manage.
12. Click Launch to load the Cloudant dashboard.

---

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. ▼More

---

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.

Replicate the animaldb database from the http://education.cloudant.com account. If you need help creating the replication request, refer to the Replication video and Tutorial on the Create a Replication Job page.

Query: https://[accountname].cloudant.com/animaldb/_all_docs

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.

---

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. ▼More

---

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.

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

Query: https://[accountname].cloudant.com/animaldb/_all_docs?limit=2&skip=3

Slicing

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

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

Query: https://[accountname].cloudant.com/animaldb/_all_docs?startkey="d"&endkey="giraffe"

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://[accountname].cloudant.com/animaldb/_all_docs?startkey="d"&endkey="giraffe"&inclusive_end=false

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

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

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.

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

Query: https://[accountname].cloudant.com/animaldb/_all_docs?key="llama"

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://[accountname].cloudant.com/animaldb/llama

Retrieving document contents

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

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

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

---