如何使用范围读取数据 - 表格存储

调用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。如果查询到的行数超过此值，则通过响应中会包含断点来记录本次读取到的位置，以便下一次读取。无论是否设置此项，表格存储最多返回的行数为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操作。说明表格存储限制GetRange操作响应消息中的数据行数不能超过5000行，数据大小不能超过4 MB。即使在GetRange请求中未设置limit，在响应消息中仍可能出现next_start_primary_key。因此使用GetRange操作时，您需要对响应消息中是否有next_start_primary_key进行处理。

使用SDK

您可以使用如下语言的SDK范围读取数据。

服务能力单元消耗

GetRange操作消耗读服务能力单元的数值为查询范围内所有行主键数据大小与实际读取的属性列数据大小之和除以4 KB向上取整。关于数据大小的计算请参见数据存储量。
如果请求超时，结果未定义，则服务能力单元有可能被消耗，也可能未被消耗。
如果返回内部错误（HTTP状态码：5XX），则此次操作不消耗服务能力单元，其他错误情况消耗1读服务能力单元。