调用UpdateRow更新指定行的数据_表格存储(Tablestore)-阿里云帮助中心

调用UpdateRow接口更新指定行的数据。

说明

如果指定行不存在，则新增一行；如果指定行存在，则根据请求的内容在该行中新增、修改或者删除指定列的值。

请求消息结构

message UpdateRowRequest {
    required string table_name = 1;
    required bytes row_change = 2;
    required Condition condition = 3;
    optional ReturnContent return_content = 4;
    optional string transaction_id = 5;
}

名称	类型	是否必选	描述
table_name	string	是	请求更新数据的表名。
row_change	bytes	是	更新的数据，包括主键和属性列，由Plainbuffer编码。更多信息，请参见Plainbuffer。该行本次需要更新的全部属性列，表格存储会根据row_change中UpdateType的内容在该行中新增、修改或者删除指定列的值。该行已存在的且不在row_change中的列将不受影响。 UpdateType的取值范围如下： PUT：此时value必须为有效的属性列值。如果该列不存在，则新增一列；如果该列存在，则覆盖该列。 DELETE：此时该value必须为空，需要指定timestamp。表示删除该列特定版本的数据。 DELETE_ALL：此时该value和timestamp都必须为空。表示删除该列所有版本的数据。说明删除本行的全部属性列不等同于删除本行。如果需要删除本行，请使用DeleteRow操作。
condition	Condition	是	在数据更新前是否进行存在性检查。取值范围如下： IGNORE（默认）：不做行存在性检查。如果忽略该行是否存在，则无论该行是否存在，都不会因此导致本次操作失败。 EXPECT_EXIST：期望行存在。如果期待该行存在但该行不存在，则本次更新操作会失败，返回错误。
return_content	ReturnContent	否	写入成功后返回的数据类型。目前仅支持返回主键，主要用于主键列自增功能中。
transaction_id	string	否	局部事务ID。当使用局部事务功能更新数据时必须设置此参数。

响应消息结构

message UpdateRowResponse {
    required ConsumedCapacity consumed = 1;
    optional bytes row = 2;
}

名称

类型

描述

consumed

ConsumedCapacity

本次操作消耗的服务能力单元。更多信息，请参见服务能力单元。

row

bytes

当设置了return_content后，返回的数据。如果未设置return_content或者没返回值，此处为NULL。

返回的数据为Plainbuffer格式。关于Plainbuffer编码的更多信息，请参见Plainbuffer。

使用SDK

您可以使用如下语言的SDK更新单行数据。

服务能力单元消耗

当更新的行不存在时，根据指定的条件检查不同，更新数据消耗的服务能力单元不同。
- 如果指定条件检查为IGNORE，则消耗写服务能力单元的数值为本行的主键数据大小与要更新的属性列数据大小之和除以4 KB向上取整。如果UpdateRow中包含有需要删除的属性列，只有其列名长度计入该属性列数据大小。
- 如果指定条件检查为EXPECT_EXIST，则本次插入失败并且消耗1单位写CU和1单位读CU。
当更新的行存在时，根据指定的条件检查不同，更新数据消耗的服务能力单元不同。
- 如果指定条件检查为IGNORE，则消耗写服务能力单元的数值为本行的主键数据大小与要更新的属性列数据大小之和除以4 KB向上取整。如果UpdateRow中包含有需要删除的属性列，只有其列名长度计入该属性列数据大小。
- 如果指定条件检查为EXPECT_EXIST，则除了需要消耗在条件检查为IGNORE情况下的写CU外，还需消耗该行主键数据大小除以4 KB向上取整的读CU。
关于数据大小的计算请参见产品定价。
如果请求超时，结果未定义，则服务能力单元有可能被消耗，也可能未被消耗。
如果返回内部错误（HTTP状态码：5XX），则此次操作不消耗服务能力单元，其他错误情况1个写服务能力单元和1个读服务能力单元。