你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

Azure Cosmos DB for NoSQL 中的分页

适用范围: NoSQL

在 Azure Cosmos DB for NoSQL 中,查询可能有多页结果。 本文档介绍 Azure Cosmos DB for NoSQL 的查询引擎用于决定是否将查询结果拆分为多个页面的条件。 可以选择使用继续标记来管理跨越多个页面的查询结果。

查询执行

有时,查询结果会拆分为多个页面。 单独的查询执行将生成每个页面的结果。 当一次执行无法返回查询结果时,Azure Cosmos DB for NoSQL 会自动将结果拆分为多个页面。

可以通过设置 MaxItemCount 来指定查询返回的最大项数。 每个请求都指定有 MaxItemCount,并通知查询引擎返回该数量或更少的项。 如果不想限制每次查询执行的结果数,可以将 MaxItemCount 设置为 -1

此外,还有查询引擎可能需要将查询结果拆分为多个页面的其他原因。 其原因包括:

  • 容器受到限制并且没有可用的 RU 来返回更多查询结果
  • 查询执行的响应太大
  • 查询执行时间过长
  • 查询引擎在额外执行中返回结果的效率更高

每次查询执行返回的项数小于或等于 MaxItemCount。 但是,其他条件可能也会限制查询可以返回的结果数。 如果多次执行同一查询,则页数可能不是固定的。 例如,如果查询受到限制,则每页的可用结果可能会较少,这意味着查询会有额外的页面。 在某些情况下,查询也有可能返回空白结果页。

处理多页结果

若要确保查询结果准确,应经历所有页面。 应继续执行查询,直至没有额外页面为止。

以下是一些多页查询处理结果的示例:

继续标记

在 .NET SDK 和 Java SDK 中,可以选择将继续标记用作查询的进度书签。 Azure Cosmos DB for NoSQL 查询执行在服务器端无状态,并可以使用延续令牌随时继续。 对于 Python SDK,只有单分区查询支持延续标记。 必须在选项对象中指定分区键,因为仅在查询中指定是不够的。

以下是一些使用继续标记的示例:

如果查询返回了延续令牌,则表示有额外查询结果。

在 Azure Cosmos DB for NoSQL 的 REST API 中,可以使用 x-ms-continuation 头管理延续令牌。 与使用 .NET 或 Java SDK 进行查询一样,如果 x-ms-continuation 响应头不为空,则表示查询还有额外结果。

只要使用相同的 SDK 版本,延续令牌就永远不会过期。 可以选择限制继续标记的大小。 不管容器中的数据量或物理分区数量如何,查询都会返回一个继续标记。

不能对具有 GROUP BYDISTINCT 的查询使用延续令牌,因为这些查询需要存储大量状态。 对于具有 DISTINCT 的查询,如果将 ORDER BY 添加到查询中,则可以使用继续标记。

以下是具有 DISTINCT 的查询(可以使用继续标记)的示例:

SELECT DISTINCT VALUE
    e.name
FROM
    employees e
ORDER BY
    e.name