GetRange
調(diào)用GetRange接口讀取指定主鍵范圍內(nèi)的數(shù)據(jù)。
請(qǐng)求消息結(jié)構(gòu)
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編碼為二進(jìn)制。
required bytes exclusive_end_primary_key = 8; // Plainbuffer編碼為二進(jìn)制。
optional bytes filter = 10;
optional string start_column = 11;
optional string end_column = 12;
}名稱 | 類型 | 是否必選 | 描述 |
table_name | string | 是 | 表名。 |
direction | 是 | 本次查詢的順序。
| |
columns_to_get | repeated string | 否 | 需要返回的全部列的列名。columns_to_get中的string個(gè)數(shù)不能超過(guò)128個(gè)。
|
time_range | 否，和max_versions只能存在一個(gè) | 讀取數(shù)據(jù)的版本時(shí)間戳范圍。時(shí)間戳的單位為毫秒，取值最小值為0，最大值為
| |
max_versions | int32 | 否，和time_range只能存在一個(gè) | 最多返回的版本個(gè)數(shù)。 如果指定max_versions為2，則每一列最多返回2個(gè)版本的數(shù)據(jù)。 |
limit | int32 | 否 | 本次讀取最多返回的行數(shù)。取值必須大于0。 如果查詢到的行數(shù)超過(guò)此值，則通過(guò)響應(yīng)中會(huì)包含斷點(diǎn)來(lái)記錄本次讀取到的位置，以便下一次讀取。 無(wú)論是否設(shè)置此項(xiàng)，表格存儲(chǔ)最多返回的行數(shù)為5000且總數(shù)據(jù)大小不超過(guò)4 MB。 |
inclusive_start_primary_key | bytes | 是 | 本次范圍讀取的起始主鍵，由Plainbuffer編碼。更多信息，請(qǐng)參見(jiàn)Plainbuffer。 如果該行存在，則響應(yīng)中一定會(huì)包含此行。 |
exclusive_end_primary_key | bytes | 是 | 本次范圍讀取的結(jié)束主鍵，由Plainbuffer編碼。更多信息，請(qǐng)參見(jiàn)Plainbuffer。 無(wú)論該行是否存在，則響應(yīng)中一定不會(huì)包含此行。 在使用GetRange操作時(shí)，inclusive_start_primary_key和exclusive_end_primary_key中Column的type支持使用特有的INF_MIN和INF_MAX兩個(gè)類型。其中類型為INF_MIN的Column小于其它Column，類型為INF_MAX的Column大于其它Column。 |
filter | bytes | 否 | 過(guò)濾條件表達(dá)式。Filter經(jīng)過(guò)protobuf序列化后的二進(jìn)制數(shù)據(jù)。 |
start_column | string | 否 | 指定讀取時(shí)的起始列，主要用于寬行讀。返回結(jié)果中會(huì)包含當(dāng)前起始列。列的順序按照列名的字典序排序。 如果表中有a、b、c三列，當(dāng)讀取數(shù)據(jù)時(shí)指定start_column為b，則會(huì)從b列開(kāi)始讀數(shù)據(jù)，返回b、c兩列。 |
end_column | string | 否 | 指定讀取時(shí)的結(jié)束列，主要用于寬行讀。返回結(jié)果中不會(huì)包含當(dāng)前結(jié)束列。列的順序按照列名的字典序排序。 如果表中有a、b、c三列，當(dāng)讀取數(shù)據(jù)時(shí)指定end_column為b，則讀到b列會(huì)結(jié)束，返回a列。 |
響應(yīng)消息結(jié)構(gòu)
message GetRangeResponse {
required ConsumedCapacity consumed = 1;
required bytes rows = 2;
optional bytes next_start_primary_key = 3;
}名稱 | 類型 | 描述 |
consumed | 本次操作消耗的服務(wù)能力單元。更多信息，請(qǐng)參見(jiàn)服務(wù)能力單元。 | |
rows | bytes | 讀取到的所有數(shù)據(jù)，由Plainbuffer編碼。更多信息，請(qǐng)參見(jiàn)Plainbuffer。
其中每行的primary_key_columns和attribute_columns均只包含在columns_to_get中指定的列，其順序不保證與請(qǐng)求中的columns_to_get一致；primary_key_columns的順序也不保證與建表時(shí)指定的順序一致。 如果在請(qǐng)求中指定的columns_to_get不包含任何主鍵列，當(dāng)某行的主鍵在查詢范圍內(nèi)，但該行沒(méi)有屬性列在columns_to_get中，則該行不會(huì)出現(xiàn)在響應(yīng)消息。 |
next_start_primary_key | bytes | 本次操作的斷點(diǎn)信息，由Plainbuffer編碼。更多信息，請(qǐng)參見(jiàn)Plainbuffer編碼。
說(shuō)明 表格存儲(chǔ)限制GetRange操作響應(yīng)消息中的數(shù)據(jù)行數(shù)不能超過(guò)5000行，數(shù)據(jù)大小不能超過(guò)4 MB。 即使在GetRange請(qǐng)求中未設(shè)置limit，在響應(yīng)消息中仍可能出現(xiàn)next_start_primary_key。因此使用GetRange操作時(shí)，您需要對(duì)響應(yīng)消息中是否有next_start_primary_key進(jìn)行處理。 |
使用SDK
您可以使用如下語(yǔ)言的SDK范圍讀取數(shù)據(jù)。
服務(wù)能力單元消耗
GetRange操作消耗讀服務(wù)能力單元的數(shù)值為查詢范圍內(nèi)所有行主鍵數(shù)據(jù)大小與實(shí)際讀取的屬性列數(shù)據(jù)大小之和除以4 KB向上取整。關(guān)于數(shù)據(jù)大小的計(jì)算請(qǐng)參見(jiàn)數(shù)據(jù)存儲(chǔ)量。
- 如果請(qǐng)求超時(shí)，結(jié)果未定義，則服務(wù)能力單元有可能被消耗，也可能未被消耗。
- 如果返回內(nèi)部錯(cuò)誤（HTTP狀態(tài)碼：5XX），則此次操作不消耗服務(wù)能力單元，其他錯(cuò)誤情況消耗1讀服務(wù)能力單元。