调用BatchWriteRow批量插入、修改和删除表数据-表格存储 Tablestore(Tablestore)-阿里云帮助中心

BatchWriteRow 是 PutRow、UpdateRow、DeleteRow 操作的集合，每个子操作独立执行、独立返回结果、独立计算服务能力单元（CU）。

与逐行调用单行写操作相比，BatchWriteRow 可有效减少请求往返次数，提升数据写入吞吐量。

请求消息结构

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

参数	类型	是否必需	描述
tables	TableInBatchWriteRowRequest	是	指定需要执行写操作的行信息。以下任一情况将返回整体错误：指定的表不存在。包含同名的表。表名不符合命名规则和数据类型命名规范。行操作未指定主键、主键列名称不符合规范或主键列类型不正确。属性列名称不符合命名规则和数据类型命名规范。属性列名称与主键列名称相同。主键列或属性列的值大小超过使用限制限制。同一表中存在主键完全相同的请求。所有表的行操作总数超过 200 个，或总数据量超过 4 MB。某张表内没有行操作，返回 OTSParameterInvalidException 错误。 PutRowInBatchWriteRowRequest 包含的列数超过 1024 个。 UpdateRowInBatchWriteRowRequest 中 ColumnUpdate 的个数超过 1024 个。
transaction_id	string	否	局部事务 ID。使用局部事务功能批量写入数据时必须设置此参数。
is_atomic	bool	否	指定批量写操作是否以原子操作方式执行。

响应消息结构

说明

BatchWriteRow 可能出现行级别的部分失败，此时返回的HTTP状态码仍为 200。需检查每个 RowInBatchWriteRowResponse 中的 is_ok 字段，确认每行的执行结果并进行相应处理。

message BatchWriteRowResponse {
    repeated TableInBatchWriteRowResponse tables = 1;
}

参数

类型

描述

tables

TableInBatchWriteRowResponse

各表中每个操作的响应信息，包括执行状态、错误码和消耗的 CU。

响应中 TableInBatchWriteRowResponse 的顺序与请求中 TableInBatchWriteRowRequest 的顺序一致；每个表内，put_rows、update_rows、delete_rows 对应的 RowInBatchWriteRowResponse 顺序，分别与请求中 PutRowInBatchWriteRowRequest、UpdateRowInBatchWriteRowRequest、DeleteRowInBatchWriteRowRequest 的顺序相同。

某行操作失败时，对应 RowInBatchWriteRowResponse 中的 is_ok 为 false。

使用 SDK

以下SDK支持 BatchWriteRow 批量写入操作：

服务能力单元消耗

如果本次操作整体失败，则不消耗任何服务能力单元。
如果请求超时，结果未定义，则服务能力单元有可能被消耗，也可能未被消耗。
其他情况下，每个 PutRowInBatchWriteRowRequest、UpdateRowInBatchWriteRowRequest、DeleteRowInBatchWriteRowRequest 均视作对应的单行写操作，独立计算读写 CU。详情请参见PutRow 服务能力单元消耗、UpdateRow 服务能力单元消耗和DeleteRow 服务能力单元消耗。