行为:
根据指定的主键读取单行数据。
message GetRowResponse {
required ConsumedCapacity consumed = 1;
required bytes row = 2; // Plainbuffer编码为二进制
}
请求结构: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;
}
table_name:
类型:string
是否必要参数:是
要读取的数据所在的表名。
primary_key:
类型:bytes
是否必要参数:是
该行全部的主键列,包含主键名和主键值,由Plainbuffer编码,详见Plainbuffer编码。
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个版本的数据。
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”列。
响应消息结构:
consumed:
row:
服务能力单元消耗:
如果请求的行不存在,消耗 1 读服务能力单元。
如果请求的行存在,消耗读服务能力单元的数值为这该行所有主键列的数据大小与实际读取的属性列数据大小之和除以 4 KB 向上取整。关于数据大小的计算请参见产品定价。
如果请求超时,结果未定义,服务能力单元有可能被消耗,也可能未被消耗。
如果返回内部错误(HTTP 状态码:5XX),则此次操作不消耗服务能力单元,其他错误情况消耗 1 读服务能力单元。