edit-icon download-icon

GetRange

最終更新日: Oct 04, 2017

GetRange

アクション:

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

リクエストの構造:

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

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”が返されます。

応答メッセージの構造:

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

consumed:

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つの読み取り容量単位が消費されます。