如何使用範圍讀取資料 - Tablestore

調用GetRange介面讀取指定主鍵範圍內的資料。

請求訊息結構

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必須小於exclusive_end_primary，響應中各行按照主鍵由小到大的順序進行排列。如果設定此項為BACKWARD（逆序），則inclusive_start_primary必須大於exclusive_end_primary，響應中各行按照主鍵由大到小的順序進行排列。
columns_to_get	repeated string	否	需要返回的全部列的列名。columns_to_get中的string個數不能超過128個。如果未設定此項或者設定此項為空白，則返回指定行的所有列。如果設定此項為指定列，當某行中指定的列均不存在時，則不返回該行，即傳回值為null；當某行中存在部分指定的列時，則返回該行且只返回存在的列。如果指定的列中存在重複的列名，則返回結果中只會包含一次該列。
time_range	TimeRange	否，和max_versions只能存在一個	讀取資料的版本時間戳記範圍。時間戳記的單位為毫秒，取值最小值為0，最大值為`INT64.MAX`。如果要查詢一個時間範圍，則指定start_time和end_time。time_range為前閉後開區間，即`[start_time,end_time)`。如果指定的time_range為`[100, 200)`，則返回的列資料的時間戳記必須處於`[100, 200)`範圍內，如果要查詢一個特定時間戳記，則指定specific_time。
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讀服務能力單元。