全部产品
Search
文档中心

表格存储:BatchWriteRow

更新时间:Jul 23, 2024

调用BatchWriteRow接口批量插入、修改或删除一个或多个表中的若干行数据。

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

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

请求消息结构

message BatchWriteRowRequest {
    repeated TableInBatchWriteRowRequest tables = 1;
    optional string transaction_id = 2;
    optional bool is_atomic = 3;
}        

参数

类型

是否必需

描述

tables

TableInBatchWriteRowRequest

指定需要执行写操作的行信息。

以下情况都会返回整体错误:

  • tables中任一表不存在。

  • tables中包含同名的表。

  • tables中任一表名不符合命名规则和数据类型

  • tables中任一行操作未指定主键、主键列名称不符合规范或者主键列类型不正确。

  • tables中任一属性列名称不符合命名规则和数据类型

  • tables中任一行操作存在与主键列同名的属性列。

  • tables中任一主键列或者属性列的值大小超过通用限制

  • tables中任一表中存在主键完全相同的请求。

  • tables中所有表总的行操作个数超过200个,或者其含有的总数据大小超过4 M。

  • tables中任一表内没有包含行操作,则返回OTSParameterInvalidException的错误。

  • tables中任一PutRowInBatchWriteRowRequest包含的Column个数超过1024个。

  • tables中任一UpdateRowInBatchWriteRowRequest包含的ColumnUpdate个数超过1024个。

transaction_id

string

局部事务ID。当使用局部事务功能批量写入数据时必须设置此参数。

is_atomic

bool

指示批量写操作是否以原子操作的形式执行。

响应消息结构

说明

BatchWriteRow操作可能会在行级别部分失败,此时返回的HTTP状态码仍为 200。应用程序必须对RowInBatchWriteRowResponse中的error进行检查,确认每一行的执行结果并进行相应的处理。

message BatchWriteRowResponse {
    repeated TableInBatchWriteRowResponse tables = 1;
}      

参数

类型

描述

tables

TableInBatchWriteRowResponse

对应了每个table下各操作的响应信息,包括是否成功执行、错误码和消耗的服务能力单元。

响应消息中TableInBatchWriteRowResponse对象的顺序与BatchWriteRowRequest中的TableInBatchWriteRowRequest对象的顺序相同;每个TableInBatchWriteRowRequest中put_rows、update_rows、delete_rows包含的RowInBatchWriteRowResponse对象的顺序分别与TableInBatchWriteRowRequest中put_rows、update_rows、delete_rows包含的PutRowInBatchWriteRowRequest、UpdateRowInBatchWriteRowRequest和DeleteRowInBatchWriteRowRequest对象的顺序相同。

如果某行读取失败,则该行所对应的RowInBatchWriteRowResponse中is_ok将为false。

使用SDK

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

服务能力单元消耗

  • 如果本次操作整体失败,则不消耗任何服务能力单元。
  • 如果请求超时,结果未定义,则服务能力单元有可能被消耗,也可能未被消耗。

  • 其他情况将每个PutRowInBatchWriteRowRequest、UpdateRowInBatchWriteRowRequestDelete、RowInBatchWriteRowRequest依次视作相对应的写操作独立计算读写服务能力单元。更多信息,请参见PutRow服务能力单元消耗UpdateRow服务能力单元消耗DeleteRow服务能力单元消耗