GetRange__API 概覽_API 參考_表格存儲-阿裏雲

行為：

讀取指定主鍵範圍內的數據。

請求結構：

message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    repeated string columns_to_get = 3;
    optional int32 limit = 4;
    repeated Column inclusive_start_primary_key = 5;
    repeated Column exclusive_end_primary_key = 6;
    optional ColumnCondition filter = 7;
}

table_name：

類型：string。
是否必要參數：是。
要讀取的數據所在的表名。

direction：

類型：Direction。
是否必要參數：是。
本次查詢的順序。若為正序，則 inclusive_start_primary 應小於 exclusive_end_primary，響應中各行按照主鍵由小到大的順序進行排列；若為逆序，則 inclusive_start_primary 應大於 exclusive_end_primary，響應中各行按照主鍵由大到小的順序進行排列。

columns_to_get：

類型：repeated string。
是否必要參數：否。
需要返回的全部列的列名。若為空，則返回讀取結果中每行的所有列。
如果給出了重複的列名，返回結果隻會包含一次該列。
columns_to_get 中 string 的個數不應超過 128 個。

limit：

類型：int32。
是否必要參數：否。
本次讀取最多返回的行數，若查詢到的行數超過此值，則通過響應中包含的斷點記錄本次讀取到的位置，以便下一次讀取。此值必須大於 0。
無論是否設置此值，表格存儲最多返回行數為 5000 且總數據大小不超過 1 M 。

inclusive_start_primary_key：

類型: repeated Column。
是否必要參數: 是。
本次範圍讀取的起始主鍵，若該行存在，則響應中一定會包含此行。

exclusive_end_primary_key：

類型：repeated Column。
是否必要參數：是。
本次範圍讀取的終止主鍵，無論該行是否存在，響應中都不會包含此行。
在 GetRange 中，inclusive_start_primary_key 和 exclusive_end_primary_key 中的 Column 的 type 可以使用本操作專用的兩個類型 INF_MIN 和 INF_MAX。類型為 INF_MIN 的 Column 永遠小於其它 Column；類型為 INF_MAX 的 Column 永遠大於其它 Column。

filter：

類型：ColumnCondition。
是否必要參數：否。
過濾條件表達式。

響應消息結構：

message GetRangeResponse {
    required ConsumedCapacity consumed = 1;
    repeated Column next_start_primary_key = 2;
    repeated Row rows = 3;
}

consumed：

類型：ConsumedCapacity。
本次操作消耗的服務能力單元。

next_start_primary_key：

類型：repeated Column。
本次 GetRange 操作的斷點信息。
若為空，則本次 GetRange 的響應消息中已包含了請求範圍內的所有數據。
若不為空，則表示本次 GetRange 的響應消息中隻包含了 [inclusive_start_primary_key, next_start_primary_key) 間的數據，若需要剩下的數據，需要將 next_start_primary_key 作為 inclusive_start_primary_key，原始請求中的 exclusive_end_primary_key 作為 exclusive_end_primary_key 繼續執行 GetRange 操作。

注意：表格存儲係統中限製了 GetRange 操作的響應消息中數據不超過 5000 行，大小不超過 4 M，並且返回的數據量不超過當前剩餘的預留讀吞吐量。即使在 GetRange 請求中未設定 limit，在響應中仍可能出現 next_start_primary_key。因此在使用 GetRange 時一定要對響應中是否有 next_start_primary_key 進行處理。

rows：

類型：repeated Row。
讀取到的所有數據，若請求中 direction 為 FORWARD，則所有行按照主鍵由小到大進行排序；若請求中 direction 為 BACKWARD，則所有行按照主鍵由大到小進行排序。
其中每行的 primary_key_columns 和 attribute_columns 均隻包含在 columns_to_get 中指定的列，其順序不保證與 request 中的 columns_to_get 一致；primary_key_columns 的順序亦不保證與建表時指定的順序一致。
如果請求中指定的 columns_to_get 不含有任何主鍵列，那麼其主鍵在查詢範圍內。但沒有任何一個屬性列在 columns_to_get 中的行將不會出現在響應消息裏。

服務能力單元消耗：

GetRange 操作消耗讀服務能力單元的數值為查詢範圍內所有行主鍵數據大小與實際讀取的屬性列數據大小之和除以 4 KB 向上取整。關於數據大小的計算請參見購買指導。
如果請求超時，結果未定義，服務能力單元有可能被消耗，也可能未被消耗。
如果返回內部錯誤（HTTP 狀態碼：5XX），則此次操作不消耗服務能力單元，其他錯誤情況消耗 1 個讀服務能力單元。

請求示例：

GetRangeRequest {
  table_name: "consume_history"
  direction: FORWARD
  columns_to_get: "CardID"
  columns_to_get: "SellerID"
  columns_to_get: "DeviceID"
  columns_to_get: "OrderNumber"
  columns_to_get: "Amount"
  columns_to_get: "Remarks"
  limit: 2
  inclusive_start_primary_key {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  inclusive_start_primary_key {
    name: "SellerID"
    value {
      type: INF_MIN
    }
  }
  inclusive_start_primary_key {
    name: "DeviceID"
    value {
      type: INF_MIN
    }
  }
  inclusive_start_primary_key {
    name: "OrderNumber"
    value {
      type: INF_MIN
    }
  }
  exclusive_end_primary_key {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  exclusive_end_primary_key {
    name: "SellerID"
    value {
      type: INF_MIN
    }
  }
  exclusive_end_primary_key {
    name: "DeviceID"
    value {
      type: INF_MIN
    }
  }
  exclusive_end_primary_key {
    name: "OrderNumber"
    value {
      type: INF_MIN
    }
  }
}

響應示例：

consumed {
  capacity_unit {
    read: 1
  }
}
next_start_primary_key {
  name: "CardID"
  value {
    type: STRING
    v_string: "2007035023"
  }
}
next_start_primary_key {
  name: "SellerID"
  value {
    type: STRING
    v_string: "00026"
  }
}
next_start_primary_key {
  name: "DeviceID"
  value {
    type: STRING
    v_string: "065499"
  }
}
next_start_primary_key {
  name: "OrderNumber"
  value {
    type: INTEGER
    v_int: 166666
  }
}
rows {
  primary_key_columns {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  primary_key_columns {
    name: "SellerID"
    value {
      type: STRING
      v_string: "00022"
    }
  }
  primary_key_columns {
    name: "DeviceID"
    value {
      type: STRING
      v_string: "061104"
    }
  }
  primary_key_columns {
    name: "OrderNumber"
    value {
      type: INTEGER
      v_int: 142857
    }
  }
  attribute_columns {
    name: "Amount"
    value {
      type: DOUBLE
      v_double: 2.5
    }
  }
  attribute_columns {
    name: "Remarks"
    value {
      type: STRING
      v_string: "ice cream"
    }
  }
}
rows {
  primary_key_columns {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  primary_key_columns {
    name: "SellerID"
    value {
      type: STRING
      v_string: "00026"
    }
  }
  primary_key_columns {
    name: "DeviceID"
    value {
      type: STRING
      v_string: "065499"
    }
  }
  primary_key_columns {
    name: "OrderNumber"
    value {
      type: INTEGER
      v_int: 153846
    }
  }
  attribute_columns {
    name: "Amount"
    value {
      type: DOUBLE
      v_double: 0.5
    }
  }
}

最後更新：2016-11-23 16:03:56