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