GetRange - Tablestore - Alibaba Cloud ドキュメントセンター

プライマリキー値が指定された範囲内にあるデータを読み取ります。

リクエスト構文

message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    repeated string columns_to_get = 3; // このパラメータを指定しない場合は、すべての列が読み取られます。
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional int32 limit = 6;
    required bytes inclusive_start_primary_key = 7; // 開始プライマリキー情報は、PlainBuffer 形式でバイナリデータとしてエンコードされます。
    required bytes exclusive_end_primary_key = 8; // 終了プライマリキー情報は、PlainBuffer 形式でバイナリデータとしてエンコードされます。
    optional bytes filter = 10;
    optional string start_column = 11;
    optional string end_column = 12;
}

パラメータ	タイプ	必須	説明
table_name	string	はい	テーブルの名前。
direction	Direction	はい	レスポンス内の行をソートする順序。このパラメータを FORWARD に設定した場合、inclusive_start_primary_key パラメータの値は exclusive_end_primary_key パラメータの値よりも小さくなければならず、レスポンス内の行はプライマリキー値の昇順でソートされます。このパラメータを BACKWARD に設定した場合、inclusive_start_primary_key パラメータの値は exclusive_end_primary_key パラメータの値よりも大きくなければならず、レスポンス内の行はプライマリキー値の降順でソートされます。
columns_to_get	repeated string	いいえ	返す列の名前。このパラメータの値には最大 128 個の文字列を含めることができます。このパラメータを指定しない場合、クエリ条件を満たす行のすべての列が返されます。行のすべての列がクエリ条件を満たさない場合、行は返されず、戻り値は null になります。行にクエリ条件を満たす列がいくつか含まれている場合、行は返され、クエリ条件を満たす列のみがレスポンスに含まれます。重複する列名が存在する場合、レスポンスには列が 1 回だけ含まれます。
time_range	TimeRange	いいえ。max_versions と time_range のいずれか 1 つのみが必要です。	読み取るデータのタイムスタンプ範囲。有効な値: 0 から `INT64.MAX`。単位: ミリ秒。タイムスタンプ範囲内のデータをクエリする場合は、start_time と end_time を指定します。time_range の値は左閉右開区間です。例: `[start_time, end_time)`。このパラメータを `[100, 200)` に設定した場合、返される列のデータのタイムスタンプは `[100, 200)` の範囲内である必要があります。特定のタイムスタンプのデータをクエリする場合は、specific_time を指定します。
max_versions	int32	いいえ。max_versions と time_range のいずれか 1 つのみが必要です。	返すデータの最大バージョン数。たとえば、max_versions の値が 2 の場合、各列に対して最大 2 つのバージョンのデータが返されます。
limit	int32	いいえ	返す行の最大数。このパラメータの値は 0 より大きくなければなりません。クエリ条件を満たす行の数がこのパラメータの値を超える場合、レスポンスには読み取り操作が終了した位置を記録するブレークポイントが含まれます。次の読み取り操作はこの位置から開始されます。 Tablestore は、このパラメータを指定するかどうかに関係なく、最大 5,000 行のデータを返します。返される行の合計サイズは 4 MB を超えることはできません。
inclusive_start_primary_key	bytes	はい	読み取り操作が開始されるプライマリキー情報。開始プライマリキー情報は PlainBuffer 形式でエンコードされます。詳細については、PlainBuffer を参照してください。行に開始プライマリキー列が含まれている場合、その行はレスポンスに含まれます。
exclusive_end_primary_key	bytes	はい	読み取り操作が終了するプライマリキー情報。終了プライマリキー情報は PlainBuffer 形式でエンコードされます。詳細については、PlainBuffer を参照してください。行に終了プライマリキー列が含まれている場合、その行はレスポンスから除外されます。 GetRange 操作の場合、inclusive_start_primary_key と exclusive_end_primary_key の値のプライマリキー列は、この操作専用の次のタイプのいずれかになります: INF_MIN と INF_MAX。INF_MIN は無限に小さい値を示します。プライマリキー列のタイプが INF_MIN の場合、列の値は他の列の値よりも小さくなります。INF_MAX は無限に大きい値を示します。プライマリキー列のタイプが INF_MAX の場合、列の値は他の列の値よりも大きくなります。
filter	bytes	いいえ	フィルタ条件の式。フィルタ条件の式は、Protobuf を使用してバイナリデータとしてシリアル化されます。詳細については、Filter を参照してください。
start_column	string	いいえ	行内で読み取り操作が開始される列。このパラメータはワイドカラム読み取りに使用されます。レスポンスには、指定された開始列が含まれます。列は名前のアルファベット順にソートされます。テーブルに列 a、b、c が含まれていて、start_column の値が b の場合、読み取り操作は列 b から開始され、列 b と c が返されます。
end_column	string	いいえ	行内で読み取り操作が終了する列。このパラメータはワイドカラム読み取りに使用されます。レスポンスには、指定された終了列は含まれません。列は名前のアルファベット順にソートされます。テーブルに列 a、b、c が含まれていて、end_column の値が b の場合、読み取り操作は列 b で終了し、列 a のみが返されます。

レスポンス構文

message GetRangeResponse {
    required ConsumedCapacity consumed = 1;
    required bytes rows = 2; 
    optional bytes next_start_primary_key = 3; 
}

パラメータ	タイプ	説明
consumed	ConsumedCapacity	操作で消費されるキャパシティユニット (CU) の数。詳細については、CU 消費量を参照してください。
rows	bytes	操作によって返される行。行は PlainBuffer 形式でエンコードされます。詳細については、PlainBuffer を参照してください。リクエストの direction が FORWARD に設定されている場合、レスポンスの行はプライマリキー値の昇順でソートされます。リクエストの direction が BACKWARD に設定されている場合、レスポンスの行はプライマリキー値の降順でソートされます。レスポンスの各行のプライマリキー列と属性列には、リクエストの columns_to_get に指定した列のみが含まれます。レスポンスの列の順序は、リクエストの columns_to_get に指定した列の順序と異なる場合があります。レスポンスのプライマリキー列の順序は、テーブルの作成時に指定されたプライマリキー列の順序と異なる場合があります。リクエストの columns_to_get の値にプライマリキー列が含まれていない場合、行のプライマリキー値がクエリ範囲内であっても、columns_to_get に指定された属性列が含まれていない行はレスポンスから除外されます。
next_start_primary_key	bytes	読み取り操作が終了した位置を記録するブレークポイント。ブレークポイントは PlainBuffer 形式でエンコードされます。詳細については、PlainBuffer を参照してください。戻り値が空の場合、GetRange 操作はクエリ条件を満たすすべてのデータを返します。戻り値が空でない場合、GetRange 操作は `[inclusive_start_primary_key, next_start_primary_key)` の範囲内のデータのみを返します。残りのデータを取得する場合は、inclusive_start_primary_key を next_start_primary_key の値に設定し、元の要求の exclusive_end_primary_key の値を保持して、GetRange 操作を再度呼び出します。説明 GetRange 操作は、リクエストごとに最大 5,000 行を返すことができます。行のデータの合計サイズは 4 MB を超えることはできません。リクエストで limit を指定しなくても、GetRange リクエストへのレスポンスに next_start_primary_key の値が含まれる場合があります。GetRange 操作を呼び出すときは、レスポンスに next_start_primary_key が含まれているかどうかを確認する必要があります。

Tablestore SDK の使用

以下の Tablestore SDK を使用して、プライマリキー値が指定された範囲内にあるデータを読み取ることができます。

Java 用 Tablestore SDK: プライマリキー値が指定された範囲内にあるデータを読み取る
Go 用 Tablestore SDK: プライマリキー値が指定された範囲内にあるデータを読み取る
Python 用 Tablestore SDK: プライマリキー値が指定された範囲内にあるデータを読み取る
Node.js 用 Tablestore SDK: プライマリキー値が指定された範囲内にあるデータを読み取る
.NET 用 Tablestore SDK: プライマリキー値が指定された範囲内にあるデータを読み取る
PHP 用 Tablestore SDK: プライマリキー値が指定された範囲内にあるデータを読み取る

CU 消費量

GetRange 操作で消費される読み取り CU の数は、次の式の計算結果から切り上げられます。消費される読み取り CU の数 = (クエリ条件を満たす行のすべてのプライマリキー列のデータサイズ + 読み取られる属性列のデータサイズ)/4 KB。データサイズの計算方法の詳細については、ストレージ使用量を参照してください。
リクエストがタイムアウトし、結果が未定義の場合、CU が消費される場合とされない場合があります。
内部エラーが発生したことを示す HTTP ステータスコード 5xx が返された場合、操作は CU を消費しません。その他のエラーが返された場合は、1 つの読み取り CU が消費されます。