Insert data by calling the PutRow operation - Tablestore

Note

If the row does not exist, PutRow creates it. If the row already exists, PutRow overwrites it.
A successful call returns no error.

Request message structure

message PutRowRequest {
    required string table_name = 1;
    required bytes row = 2; // Plainbuffer-encoded binary data.
    required Condition condition = 3;
    optional ReturnContent return_content = 4;
    optional string transaction_id = 5;
}

Name	Type	Required	Description
table_name	string	Yes	The name of the table to write data to.
row	bytes	Yes	The row data to write, including primary key columns and attribute columns. Encoded in Plainbuffer format. For more information, see Plainbuffer.
condition	Condition	Yes	Controls whether Tablestore checks for the row before writing. Valid values: IGNORE (default): Skips the existence check. EXPECT_EXIST: Requires the row to exist before writing. EXPECT_NOT_EXIST: Requires the row to not exist before writing.
return_content	ReturnContent	No	The type of data to return after a successful write. Only the primary key can be returned. Use this parameter with the auto-increment primary key column feature.
transaction_id	string	No	The local transaction ID. Required when writing data within a local transaction.

Response message structure

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

Name

Type

Description

consumed

ConsumedCapacity

The capacity units consumed by this operation. For details, see Capacity unit consumption.

row

bytes

The returned row data. Only present when return_content is set. If return_content is not set or no data is returned, this field is NULL.

The returned data is encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.

Use an SDK

The following SDKs support inserting a single row of data.

Capacity unit consumption

If the row does not exist, capacity unit consumption depends on the condition check.
- IGNORE: Consumes write capacity units (WCUs). WCUs = ceil((primary key size + attribute column size) / 4 KB).
- EXPECT_NOT_EXIST: Consumes both WCUs and read capacity units (RCUs). WCUs = ceil((primary key size + attribute column size) / 4 KB). RCUs = ceil(primary key size / 4 KB).
- EXPECT_EXIST: The write fails and consumes 1 WCU and 1 RCU.
If the row exists, capacity unit consumption depends on the condition check.
- IGNORE: Consumes WCUs. WCUs = ceil((primary key size + attribute column size) / 4 KB).
- EXPECT_EXIST: Consumes both WCUs and RCUs. WCUs = ceil((primary key size + attribute column size) / 4 KB). RCUs = ceil(primary key size / 4 KB).
- EXPECT_NOT_EXIST: The write fails and consumes 1 WCU and 1 RCU.
For information on how data size is calculated, see Pricing.
For a conditional update, consumption is calculated as above on success. On failure, the operation consumes 1 WCU and 1 RCU.
If the request times out and the results are undefined, CUs may or may not be consumed.
An internal error (HTTP status code 5xx) does not consume capacity units. All other errors consume 1 WCU.