---
name: Cloudant-cloudant-query
title: Working with IBM Cloudant Query
description: 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.
last-updated: 2026-07-06
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/Cloudant?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Working with IBM Cloudant Query
{: #query}

## Overview
{: #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.
{: shortdesc}

## How IBM Cloudant Query works
{: #query-how-it-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](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-selector-syntax&format=markdown).

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

1. 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.
2. 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:

- [Working with JSON indexes](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-json-indexes&format=markdown).
- [Working with text indexes](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-text-indexes&format=markdown).
- [Partial indexes](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-partial-indexes&format=markdown).

## When to use IBM Cloudant Query
{: #query-when-to-use}

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
{: #query-when-not-to-use}

Avoid Query for:

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

## Pagination
{: #query-pagination}

Use [bookmark pagination](https://cloud.ibm.com/docs/apis/cloudant/cloudant-gen1#bookmark-pagination) for selector syntax queries.
For specific details and examples see the API documentation topic [Paging on selector syntax queries](https://cloud.ibm.com/docs/apis/cloudant/cloudant-gen1#paging-on-selector-syntax-queries).