:GetRange

GetRange

アクション:

指定されたプライマリキー範囲のデータを読み取ります。

リクエストの構造:

message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    repeated string columns_to_get = 3;  // If it is not specified, all columns are read
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional int32 limit = 6;
    required bytes inclusive_start_primary_key = 7; // The Plainbuffer encoding is binary
    required bytes exclusive_end_primary_key = 8; // The Plainbuffer encoding is binary
    optional bytes filter = 10;
    optional string start_column = 11;
    optional string end_column = 12;
}

table_name:

• 型: 文字列

• 必須パラメーター: はい

• 読み取るデータを保持するテーブルの名前。

direction:

• 型: Direction

• 必須パラメーター: はい

• クエリの方向が順方向の場合、inclusive_start_primary は exclusive_end_primary よりも小さくなる必要があり、応答では、最小のプライマリキーから順に最大のプライマリキーへ行が並べ替えられます。クエリの方向が逆方向の場合、inclusive_start_primary は exclusive_end_primary よりも大きくなる必要があり、応答では、最大のプライマリキーから順に最小のプライマリキーへ行が並べ替えられます。

columns_to_get:

• 型: repeated string

• 必須パラメーター: いいえ

• 返されるすべての列の名前。null の場合、返される結果の各行のすべての列が読み取られます。

• 重複する列名が指定された場合、戻り結果にはこの列は一度しか含まれません。

• columns_to_get では、文字列の数が 128 を超えないようにする必要があります。

time_range:

• 型: TimeRange

• 必須パラメーター: time_rangeまたはmax_versionsのいずれかが必要です。

• データのバージョンを読み取るためのタイムスタンプの範囲。

• タイムスタンプの最小値と最大値は、それぞれ0とINT64.MAXです。

• 時間範囲のデータを照会するには、start_timeとend_timeを指定します。

• 特定のタイムスタンプのデータを照会するには、specific_timeを指定します。

• 例：time_rangeの値が（100,200）の場合、返される列データのタイムスタンプは[100,200]以内でなければなりません。

max_versions：

• 型: int32

• 必須パラメーター: time_rangeまたはmax_versionsのいずれかが必要です。

• 返されるデータのバージョンの最大数。

• 例：max_versionsの値が2の場合、各列に対して最大2つのバージョンのデータが返されます。

limit:

• 型: int32

• 必須パラメーター: いいえ

• この値は、1 回の操作で読み取る、返されるデータ行の最大数を指定します。照会された行数がこの値を超えた場合、応答には、この操作で読み取りが終わった位置を記録し、次の読み取りを簡単にするためのブレークポイントが含まれます。この値は 0 より大きくする必要があります。

• この値の設定の有無にかかわらず、OTS は最大 5000 データ行を返します。合計データ量が 4 M を超えることはできません。

inclusive_start_primary_key：

• 型: Bytes

• 必須パラメーター: はい

• 読み取る範囲の開始主キーを含む行。この行が存在する場合、応答には必ず含まれます。Plainbuffer形式でエンコードされます。詳細は、Plainbuffer encodingを参照してください。

exclusive_end_primary_key：

• 型: Bytes

• 必須パラメーター: はい

• 読み取る範囲の終了主キーを含む行。応答には、行が存在するかどうかに関係なく、行は含まれません。Plainbuffer形式でエンコードされます。詳細は、Plainbuffer encodingを参照してください。

• GetRangeの場合、inclusive_start_primary_keyまたはexclusive_end_primary_keyの列は、INF_MINまたはINF_MAXに特化できます。列がINF_MINに設定されている場合、列の値は常に他の列の値よりも小さくなります。列がINF_MAXに設定されている場合、その値は常に他の列よりも大きくなります。

filter:

• 型: Bytes

• 必須パラメーター: いいえ

• フィルタリング条件式。

• Filter をProtobuf形式でシリアル化した後のバイナリデータを示します。

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

• この操作で消費された容量単位。

rows：

• 型: Bytes

• Plainbuffer形式でエンコードされます。詳細は、Plainbuffer encodingを参照してください。

• すべてのデータが読み込まれます。要求の方向がFORWARDの場合、すべての行が最小の主キーから最大の主キーにソートされます。要求の方向がBACKWARDの場合、すべての行が最大の主キーから最小の主キーにソートされます。

• ここでは、各行のprimary_key_columnsおよびattribute_columnsには、columns_to_getで指定された列のみが含まれます。それらの順序は、要求のcolumns_to_getの順序と一致しないことがあります。また、primary_key_columnsの順序は、表の作成時に指定された順序と一致しないこともあります。

• 要求の指定されたcolumns_to_getに主キー列が含まれていない場合、主キーはクエリ範囲内にあります。ただし、columns_to_getに属性列を含まない行は応答メッセージに含まれません。

next_start_primary_key：

• 型: Bytes

• このGetRange操作のブレークポイント情報。Plainbuffer形式でエンコードされます。詳細は、 Plainbuffer encodingを参照してください。

• nullの場合、このGetRange操作の応答メッセージには、要求範囲内のすべてのデータが含まれます。

• nullでない場合、このGetRange操作の応答メッセージには、[inclusive_start_primary_key、next_start_primary_key]の範囲のデータのみが含まれます。残りのデータが必要な場合は、next_start_primary_keyをinclusive_start_primary_keyとして使用し、後続のGetRange操作を実行する元の要求にexclusive_end_primary_keyを保持する必要があります。

注意: テーブルストアシステムでは、GetRange操作の応答メッセージのデータ行数は5,000を超えることはできず、サイズは4 MBを超えることはできません。さらに、返されるデータの量は、現在残っている予約済みの読み取りスループットを超えることはできません。GetRange要求に制限が設定されていない場合でも、next_start_primary_keyが応答に表示されることがあります。したがって、GetRangeを使用する場合は、レスポンスにnext_start_primary_keyが処理されるかどうかをチェックする必要があります。

容量単位消費量：

• GetRange操作で消費される読み取り容量単位の数は、クエリ範囲内のすべてのデータ行の主キーのサイズと実際に読み取られた属性列のサイズを4 KBで除算して切り上げたものです。データサイズを計算する方法の詳細については、 Billingを参照してください。

• 要求がタイムアウトして結果が未定義の場合、容量単位が消費される場合と消費されない場合があります。

• 内部エラーコードが返された場合（HTTPステータスコード：5XX）、この操作は容量単位を消費しません。他のエラーが返された場合は、1つの読み取り容量単位が消費されます。