Using the Primary Index
The primary index is the fastest way to retrieve data from your database. If you learn better by seeing a demonstration, watch these videos first:
Provision the IBM Cloudant Service in Bluemix
- Visit IBM Bluemix at http://console.ng.bluemix.net.
- If you don't have a Bluemix account, click Sign Up. Complete the fields on the form, and click Create Account.
- If you have a Bluemix account, click Log In. Provide your IBMid and password, and click Log In.
- In the top navigation bar, click Catalog.
- In the left navigator, under Services, check Data and Analytics.
- Click Cloudant NOSQL DB.
- Accept the default service, or provide a different name, and click Create. This brings you to the IBM Cloudant Bluemix Service Launch Page.
- 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.
- Paste the value for your username here:
- Click this button to update the URLs for the rest of this tutorial.
- Click Manage.
- Click Launch to load the Cloudant dashboard.
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.
All indexes are sorted by their key. The sort order is:
- text, cases sensitive - lower case first
- arrays, sorted element by element
The full specification is documented in the CouchDB Wiki.
Review the API Options
_all_docsrequest 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
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
In this call, we
limit the result set to 2 rows and
skip the first 3 rows.
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
If you don't want to include documents that match the end key, add the
inclusive_end parameter with a value of
View slicing with
endkey can be combined with
inclusive_end to further constrain your result set.
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
Here, we're looking for a document indexed with the key of "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.
Retrieving document contents
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
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.
Find more videos and tutorials in the Cloudant Learning Center.