![\"Image](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/01\/paginationCosmosDB.png\")
<\/a><\/p>\nOnly 10 results are shown on the first page, but you can select to go to a later page if you want more results:<\/p>\n
Why is it beneficial to break up the results into multiple pages? There are a few reasons:<\/p>\n In Azure Cosmos DB, there are similar reasons why queries can be split up into multiple pages of results:<\/p>\n There are also cases where the query engine returns results in multiple pages because it\u2019s better for query performance. This is common for cross-partition queries, where you\u2019ll occasionally get an empty page of results returned if there aren\u2019t results from all physical partitions. The query engine may also split up results due to throttling.<\/p>\n <\/p>\n Pagination tips<\/strong><\/p>\n Your code should always be able to handle the case where query results span multiple pages. Here\u2019s a query pagination example using the .NET SDK. <\/a>The Azure Cosmos DB SDK does most of the work for you. Including a while loop is essential here, allowing the query to keep running until there are no more results.<\/p>\n If you want to stop your query and resume it later, you can extract a continuation token. A continuation token is a string (up to 16 KB) that the query engine can use to continue the query without having to repeat previous executions leading up to that point. You can limit continuation token size if needed, but we recommend keeping it as high as your application allows. Here\u2019s how to do pagination with continuation tokens.<\/a><\/p>\n Getting query results as quickly as possible<\/strong><\/p>\n In some cases, you might want your query to return as much data as it can, as quickly as possible. The best way to do this is by minimizing the number of round trips that your application needs to make to Azure Cosmos DB.<\/p>\n In this case, you should set MaxItemCount<\/strong> to -1<\/strong> in your QueryOptions. In most Azure Cosmos DB SDK versions, MaxItemCount defaults to 100. With that default setting, queries are limited to returning 100 items per query page, regardless of whether the query is close to hitting the 4 MB limit per page limit or 5 second query execution limit. If the query engine can return more results in each page, the query will require fewer round trips.<\/p>\n Here\u2019s an example:<\/p>\n Retrieving an exact number of query results<\/strong><\/p>\n Many applications want to obtain an exact number of query results. In the earlier Bing search example, the server returned 10 results per page. In that case, while it was important to have a maximum of 10 results per page, it was also totally fine if there were fewer than 10 results. However, there are other instances where you might want an exact number of results returned.<\/p>\n Here\u2019s one approach to get an exact number of query results, assuming exactly 10 results are desired:<\/p>\n Cancelling expensive queries<\/strong><\/p>\n An expensive query can quickly consume a significant amount of your provisioned throughput. Each time a page of query results is returned, you can check the query\u2019s RU charge and, if necessary, stop progressing to the next page. Because a query will return results after 5 seconds, this limits the damage from an unexpectedly expensive query. When a query is executing, you cannot stop execution until the query engine returns a response for that page.<\/p>\n Here\u2019s an example for you to adjust your code to support stopping expensive queries:<\/p>\n Learn more about query pagination in Azure Cosmos DB: <\/strong><\/p>\n In this blog, we’ll take a look at tips for query pagination in Azure Cosmos DB. Pagination is the process of dividing a large volume of data across many small pages.<\/p>\n","protected":false},"author":12128,"featured_media":3896,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[14,818,19],"tags":[],"class_list":["post-3892","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-core-sql-api","category-query","category-tips-and-tricks"],"acf":[],"blog_post_summary":" In this blog, we’ll take a look at tips for query pagination in Azure Cosmos DB. Pagination is the process of dividing a large volume of data across many small pages.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/3892","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/12128"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=3892"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/3892\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/3896"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=3892"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=3892"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=3892"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}<\/a><\/p>\n\n
\n
string sqlQuery = \"SELECT TOP 20 * FROM c WHERE c.Item = 'shirt' AND c.Price > 75\";\r\n\r\nQueryDefinition query = new QueryDefinition(sqlQuery);\r\n\r\nFeedIterator<Item> resultSetIterator = exampleApp.container.GetItemQueryIterator<Item>(\r\nquery, requestOptions: new QueryRequestOptions\r\n {\r\n MaxItemCount = -1\r\n }\r\n);<\/pre>\n\n
double totalRUsConsumed = 0;\r\ndouble budgetRUs = 100;\r\n\r\nFeedIterator<Item> resultSetIterator = exampleApp.container.GetItemQueryIterator<Item>(\r\nquery, requestOptions: new QueryRequestOptions\r\n {\r\n MaxItemCount = -1\r\n });\r\n\r\nFeedResponse<Item> response;\r\n\r\nwhile (resultSetIterator.HasMoreResults)\r\n{\r\n response = await resultSetIterator.ReadNextAsync();\r\n totalRUsConsumed = totalRUsConsumed + response.RequestCharge;\r\n\r\n if (totalRUsConsumed > budgetRUs)\r\n {\r\n throw new Exception(\"RUs budget exceeded!\");\r\n }\r\n}\r\n<\/pre>\n\n