Azure Cosmos DB for NoSQL での改ページ
適用対象: 
NoSQL
Azure Cosmos DB for NoSQL では、クエリが複数ページの結果となる場合があります。 このドキュメントでは、Azure Cosmos DB for NoSQL のクエリ エンジンがクエリ結果を複数のページに分割するかどうかを決定するために使用する基準について説明します。 複数ページにまたがるクエリ結果を管理するために、オプションで継続トークンを使用できます。
クエリ実行
クエリ結果が複数のページに分割される場合があります。 個々のクエリ実行が各ページの結果を生成します。 クエリ結果を 1 回の実行で返すことができない場合、Azure Cosmos DB for NoSQL は自動的に結果を複数のページに分割します。
MaxItemCount を設定すると、1 回のクエリで返される項目の最大数を指定できます。 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 バージョンを使用している限り、継続トークンは期限切れになりません。 必要に応じて、継続トークンのサイズを制限することができます。 コンテナー内のデータ量や物理パーティション数に関係なく、クエリから返される継続トークンは 1 つです。
GROUP BY や DISTINCT を含むクエリに対しては、継続トークンを使用できません。これらのクエリでは、大量の状態を保存する必要があるためです。 DISTINCT を含むクエリに対しては、ORDER BY をクエリに追加すると、継続トークンを使用できます。
DISTINCT を含み、継続トークンが使用できるクエリの例を次に示します。
SELECT DISTINCT VALUE
e.name
FROM
employees e
ORDER BY
e.name