调用GetRow接口读取单行数据_表格存储(Tablestore)-阿里云帮助中心

调用GetRow接口根据指定的主键读取单行数据。

请求消息结构

message GetRowRequest {
    required string table_name = 1;
    required bytes primary_key = 2;   // Plainbuffer编码为二进制。
    repeated string columns_to_get = 3; // 不指定则读出所有的列。
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional bytes filter = 7;
    optional string start_column = 8;
    optional string end_column = 9;
    optional bytes token = 10;
    optional string transaction_id = 11;
}

名称	类型	是否必选	描述
table_name	string	是	要读取的数据所在的表名。
primary_key	bytes	是	指定行全部的主键列，包含主键名和主键值，由Plainbuffer编码。更多信息，请参见Plainbuffer。
columns_to_get	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个版本的数据。
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列。
token	bytes	否	宽行读取时指定下一次读取的起始位置，暂不可用。
transaction_id	string	否	局部事务ID。当使用局部事务功能读取数据时必须设置此参数。

响应消息结构

message GetRowResponse {
    required ConsumedCapacity consumed = 1;
    required bytes row = 2; // Plainbuffer编码为二进制
    optional bytes next_token = 3;
}

名称	类型	描述
consumed	ConsumedCapacity	本次操作消耗的服务能力单元。更多信息，请参见服务能力单元消耗。
row	bytes	读取到的数据。如果该行不存在，则数据为空。返回的数据为Plainbuffer格式。关于Plainbuffer编码的更多信息，请参见Plainbuffer。
next_token	bytes	读请求一行数据中列数超过128列，会返回next_token。

使用SDK

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

服务能力单元消耗

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