適用於 NoSQL 的 Azure Cosmos DB 中的分頁
適用於：
NoSQL
在適用於 NoSQL 的 Azure Cosmos DB 中，查詢可能會有多個頁面的結果。 本文件說明適用於 NoSQL 的 Azure Cosmos DB 查詢引擎用來決定是否要將查詢結果分割成多個頁面的準則。 您可以選擇性地使用接續權杖來管理跨越多個頁面的查詢結果。
查詢執行
有時候查詢結果會分割成多個頁面。 個別的查詢執行會產生每個頁面的結果。 當單一執行中無法傳回查詢結果時，適用於 NoSQL 的 Azure Cosmos DB 會自動將結果分割成多個頁面。
您可以藉由設定 MaxItemCount 來指定查詢所傳回的項目數上限。 MaxItemCount 是針對每個要求所指定，並告知查詢引擎傳回該數量的項目或較少的項目。 如果您不想限制每個查詢執行的結果數目，您可以將 MaxItemCount 設定為 -1。
此外，查詢引擎還有其他原因可能需要將查詢結果分割成多個頁面。 這些原因包括：
- 容器已進行節流，而且沒有可用的 RU 可傳回更多查詢結果
- 查詢執行的回應太大
- 查詢執行的時間太長
- 查詢引擎在額外執行中傳回結果更有效率
每個查詢執行所傳回的項目數目小於或等於 MaxItemCount。 不過，其他準則可能會限制查詢可能傳回的結果數目。 如果您多次執行相同的查詢，則頁面數目可能不會是常數。 例如，如果查詢受到節流，每個頁面的可用結果可能會較少，這表示查詢有額外的頁面。 在某些情況下，您的查詢也可能傳回結果的空白頁面。
處理多個結果頁面
為了確保正確的查詢結果，您應該進行所有頁面的進度。 您應該繼續執行查詢，直到沒有額外的頁面為止。
以下是使用多個頁面處理查詢結果的一些範例：
接續權杖
在 .NET SDK 和 Java SDK 中，您可以選擇性地使用接續令牌作為查詢進度的書籤。 適用於 NoSQL 的 Azure Cosmos DB 查詢執行在伺服器端是無狀態的，而且可以隨時使用接續令牌繼續執行。 針對 Python SDK，只有單一分割區查詢才支援接續令牌。 數據分割索引鍵必須在options物件中指定，因為它不足以在查詢本身中擁有它。
以下是使用接續權杖的一些範例：
如果查詢傳回接續令牌，則會有額外的查詢結果。
在適用於 NoSQL 的 REST API 的 Azure Cosmos DB 中，您可以使用標頭來管理接續令牌 x-ms-continuation 。 如同使用 .NET 或 Java SDK 進行查詢，如果響應標頭不是空的 x-ms-continuation ，則表示查詢有額外的結果。
只要您使用相同的 SDK 版本，接續令牌永遠不會過期。 您可以選擇性地限制接續權杖的大小。 無論您容器中的資料量或實體分割區數目為何，查詢都會傳回單一的接續權杖。
您無法針對 GROUP BY 或 DISTINCT 的查詢使用接續令牌，因為這些查詢需要儲存大量的狀態。 針對使用 DISTINCT 的查詢，您可以在將 ORDER BY 新增至查詢時使用接續標記。
以下是具有 DISTINCT 且可使用接續權杖的查詢範例：
SELECT DISTINCT VALUE
e.name
FROM
employees e
ORDER BY
e.name