Working with IBM Cloudant Query

Overview

IBM Cloudant Query is a flexible query language that allows fetching documents from a database that match a "selector" -- a JSON object that defines the search criteria.

How IBM Cloudant Query works

To use IBM Cloudant Query, you send JSON-formatted queries to the _find HTTP endpoint of a database. The JSON contains a selector which defines the query itself, alongside metadata such as the sort order to use when returning documents. The selector syntax is loosely based on MongoDB's query language, offering a rich set of query operators that can be combined to make complex queries.

Start learning about queries by reading Selector syntax.

To ensure queries return results quickly, IBM Cloudant Queries should be backed by a suitable secondary index. There are two types of indexes available:

JSON indexes (type=json, the default) - a set of nominated document fields combined together to form the index keyspace. A query's selector and sort parameters must match an index's keys for it to be used when processing the query.
Text indexes (type=text) - a set of nominated document fields indexed separately. One or more of the indexed fields can be combined in selector expressions to extract small slices of data (up to 200 documents per query).

IBM Cloudant queries can act on the entire database, or for partitioned databases, on a single partition.

Learn about creating indexes by reading:

When to use IBM Cloudant Query

IBM Cloudant Query is ideal for:

Operational queries where a query's selector/sort match a pre-defined type=json index.
Ad-hoc queries on one or more fields backed by a type=text index, for small result sets.
Creating partial indexes, where a subset of the documents are used to form the index and the selector/sort further filters the indexed data.

When not to use IBM Cloudant Query

Avoid Query for:

Data aggregation. Use Views instead.
Free-text or wildcard searching. Use Cloudant Search instead.