Azure Cosmos DB 中的分页Pagination in Azure Cosmos DB

适用于: SQL API

在 Azure Cosmos DB 中,查询可能有多页结果。In Azure Cosmos DB, queries may have multiple pages of results. 本文档介绍 Azure Cosmos DB 查询引擎用于决定是否将查询结果拆分为多个页面的条件。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. 当一次执行无法返回查询结果时,Azure Cosmos DB 会自动将结果拆分为多个页面。When query results cannot be returned in one single execution, Azure Cosmos DB will automatically split results into multiple pages.

可以通过设置 MaxItemCount 来指定查询返回的最大项数。You can specify the maximum number of items returned by a query by setting the MaxItemCount. MaxItemCount 是按请求指定的,它指示查询引擎将返回该数量的项或更少的项。The MaxItemCount is specified per request and tells the query engine will to return that number of items or fewer. 如果不想限制每次查询执行的结果数,可以将 MaxItemCount 设置为 -1You 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:

  • 容器受到限制并且没有可用的 RU 来返回更多查询结果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

每次查询执行返回的项数将始终小于或等于 MaxItemCountThe 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

在 .NET SDK 和 Java SDK 中,可以选择将继续标记用作查询的进度书签。In the .NET SDK and Java SDK, you can optionally use continuation tokens as a bookmark for your query's progress. Azure Cosmos DB 查询执行在服务器端无状态,并可以使用继续标记随时恢复。Azure Cosmos DB query executions are stateless at the server side and can be resumed at any time using the continuation token. Node.js SDK 不支持延续令牌。Continuation tokens are not supported in the Node.js SDK. 对于 Python SDK,单分区查询支持延续令牌,必须在选项对象中指定 PK,因为在查询本身中指定它是不够的。For the Python 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.

在 Azure Cosmos DB 的 REST API 中,可以使用 x-ms-continuation 标头管理继续标记。In Azure Cosmos DB's REST API, you can manage continuation tokens with the x-ms-continuation header. 与使用 .NET 或 Java SDK 进行查询一样,如果 x-ms-continuation 响应标头不为空,则表示查询还有其他结果。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.

只要使用相同的 SDK 版本,继续标记就永远不会过期。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.

不能对具有 GROUP BYDISTINCT 的查询使用继续标记,因为这些查询需要存储大量状态。You cannot use continuation tokens for queries with GROUP BY or DISTINCT because these queries would require storing a significant amount of state. 对于具有 DISTINCT 的查询,如果将 ORDER BY 添加到查询中,则可以使用继续标记。For queries with DISTINCT, you can use continuation tokens if you add ORDER BY to the query.

以下是具有 DISTINCT 的查询(可以使用继续标记)的示例:Here's an example of a query with DISTINCT that could use a continuation token:


后续步骤Next steps