调用BatchGetRow接口批量读取一个表或多个表中的若干行数据。

BatchGetRow操作可视为多个GetRow操作的集合,各个操作独立执行,独立返回结果,独立计算服务能力单元。

与执行大量的GetRow操作相比,使用BatchGetRow操作可以有效减少请求的响应时间,提高数据的读取速率。

请求消息结构

message BatchGetRowRequest {
    repeated TableInBatchGetRowRequest tables = 1;
}           
参数 类型 是否必需 描述
tables repeated TableInBatchGetRowRequest 指定了需要要读取的行信息。

如果tables中出现了下述情况,则操作整体失败,返回错误。

  • tables中任一表不存在。
  • tables中任一表名不符合命名规则和数据类型
  • tables中任一行未指定主键、主键名称不符合规范或者主键类型不正确。
  • tables中任一表的columns_to_get内的列名不符合命名规则和数据类型
  • tables中包含同名的表。
  • tables中任一表中包含主键完全相同的行。
  • 所有tables中RowInBatchGetRowRequest的总个数超过100个。
  • tables中任一表中不包含任何RowInBatchGetRowRequest。
  • tables中任一表的columns_to_get超过128列。

响应消息结构

说明 BatchGetRow操作可能会在行级别部分失败,此时返回的HTTP状态码仍为200。应用程序必须对RowInBatchGetRowResponse中的error进行检查确认每一行的执行结果,并进行相应的处理。
message BatchGetRowResponse {
    repeated TableInBatchGetRowResponse tables = 1;
}          
参数 类型 描述
tables repeated TableInBatchGetRowResponse 对应每个table下读取到的数据。

响应消息中TableInBatchGetRowResponse对象的顺序与BatchGetRowRequest中的TableInBatchGetRowRequest对象的顺序相同;每个TableInBatchGetRowResponse下的RowInBatchGetRowResponse对象的顺序与TableInBatchGetRowRequest下的RowInBatchGetRowRequest相同。

如果某行不存在或者某行在指定的columns_to_get中没有数据,仍然会在TableInBatchGetRowResponse中有一条对应的RowInBatchGetRowResponse,但其row下的primary_key_columns和attribute_columns将为空。

如果某行读取失败,则该行所对应的RowInBatchGetRowResponse中is_ok将为false,此时row将为空。

使用SDK

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

服务能力单元消耗

  • 如果本次操作整体失败,则不消耗任何服务能力单元。
  • 如果请求超时,结果未定义,则服务能力单元有可能被消耗,也可能未被消耗。
  • 其他情况将每个RowInBatchGetRowRequest视为一个GetRow操作独立计算读服务能力单元。更多信息,请参见GetRow服务能力单元消耗