Pagination in Azure Cosmos DB

APPLIES TO: SQL API

In Azure Cosmos DB, queries may have multiple pages of results. This document explains criteria that Azure Cosmos DB's query engine uses to decide whether to split query results into multiple pages. You can optionally use continuation tokens to manage query results that span multiple pages.

Understanding query executions

Sometimes query results will be split over multiple pages. Each page's results is generated by a separate query execution. When query results cannot be returned in one single execution, Azure Cosmos DB will automatically split results into multiple pages.

You can specify the maximum number of items returned by a query by setting the MaxItemCount. The MaxItemCount is specified per request and tells the query engine to return that number of items or fewer. You can set MaxItemCount to -1 if you don't want to place a limit on the number of results per query execution.

In addition, there are other reasons that the query engine might need to split query results into multiple pages. These include:

  • The container was throttled and there weren't available RUs to return more query results
  • The query execution's response was too large
  • The query execution's time was too long
  • It was more efficient for the query engine to return results in additional executions

The number of items returned per query execution will always be less than or equal to MaxItemCount. However, it is possible that other criteria might have limited the number of results the query could return. If you execute the same query multiple times, the number of pages might not be constant. For example, if a query is throttled there may be fewer available results per page, which means the query will have additional pages. In some cases, it is also possible that your query may return an empty page of results.

Handling multiple pages of results

To ensure accurate query results, you should progress through all pages. You should continue to execute queries until there are no additional pages.

Here are some examples for processing results from queries with multiple pages:

Continuation tokens

In the .NET SDK and Java SDK you can optionally use continuation tokens as a bookmark for your query's progress. Azure Cosmos DB query executions are stateless at the server side and can be resumed at any time using the continuation token. For the Python SDK and Node.js SDK, it's supported for single partition queries, and the PK must be specified in the options object because it's not sufficient to have it in the query itself.

Here are some example for using continuation tokens:

If the query returns a continuation token, then there are additional query results.

In Azure Cosmos DB's REST API, you can manage continuation tokens with the x-ms-continuation header. As with querying with the .NET or Java SDK, if the x-ms-continuation response header is not empty, it means the query has additional results.

As long as you are using the same SDK version, continuation tokens never expire. You can optionally restrict the size of a continuation token. Regardless of the amount of data or number of physical partitions in your container, queries return a single continuation token.

You cannot use continuation tokens for queries with GROUP BY or DISTINCT because these queries would require storing a significant amount of state. For queries with DISTINCT, you can use continuation tokens if you add ORDER BY to the query.

Here's an example of a query with DISTINCT that could use a continuation token:

SELECT DISTINCT VALUE c.name
FROM c
ORDER BY c.name

Next steps