GetRange - Tablestore

請求訊息結構

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	是	本次查詢的順序。如果為正序，則inclusive_start_primary應小於exclusive_end_primary，響應中各行按照主鍵由小到大的順序進行排列。如果為逆序，則inclusive_start_primary應大於exclusive_end_primary，響應中各行按照主鍵由大到小的順序進行排列。
columns_to_get	repeated string	否	需要返回的全部列的列名。如果為空白，則返回指定行的所有列。columns_to_get中string的個數不應超過128個。如果給出了重複的列名，返回結果只會包含一次該列。
time_range	TimeRange	否，和max_versions只能存在一個	讀取資料的版本時間戳記範圍。時間戳記的單位為毫秒，取值最小值為0，最大值為INT64.MAX。如果要查詢一個範圍，則指定start_time和end_time。如果要查詢一個特定時間戳記，則指定specific_time。如果指定的time_range為[100, 200)，則返回的列資料的時間戳記必須位於[100, 200)範圍內，前閉後開區間。
max_versions	int32	否，和time_range只能存在一個	讀取資料時，最多返回的版本個數。如果指定max_versions為2，則每一列最多返回2個版本的資料。
limit	int32	否	本次讀取最多返回的行數。如果查詢到的行數超過此值，則通過響應中包含的斷點記錄本次讀取到的位置，以便下一次讀取。此值必須大於 0。無論是否設定此值，Table Store最多返回的行數為5000且總資料大小不超過 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中的Column的type可以使用本操作專用的兩個類型INF_MIN和INF_MAX。類型為INF_MIN的Column小於其它Column，類型為INF_MAX的Column大於其它Column。
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。如果請求中direction為FORWARD，則所有行按照主鍵由小到大進行排序；如果請求中direction為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	本次操作的斷點資訊，由Plainbuffer編碼。更多資訊，請參見Plainbuffer編碼。若為空白，則本次 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 操作。说明 Table Store系統中限制了 GetRange 操作的響應訊息中資料不超過 5000 行，大小不超過 4 MB。即使在 GetRange 請求中未設定 limit，在響應中仍可能出現 next_start_primary_key。因此在使用 GetRange 時一定要對響應中是否有 next_start_primary_key 進行處理。

使用SDK

您可以使用如下語言的SDK範圍讀取資料。

服務能力單元消耗

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