All Products
Search
Document Center

Tablestore:PutRow

Last Updated:Aug 08, 2024

Writes data to a row.

Note
  • If the specified row does not exist, a new row is added. If the specified row exists, the row is overwritten.

  • If the response to the request does not contain errors, the request is successful.

Request syntax

message PutRowRequest {
    required string table_name = 1;
    required bytes row = 2; // The data is encoded as binary data in the PlainBuffer format. 
    required Condition condition = 3;
    optional ReturnContent return_content = 4;
    optional string transaction_id = 5;
}           

Parameter

Type

Required

Description

table_name

string

Yes

The name of the table to which you want to write data.

row

bytes

Yes

The data that you want to write to the row, including primary key columns and attribute columns. The data is encoded in the PlainBuffer format. For more information about PlainBuffer, see PlainBuffer.

condition

Condition

Yes

Specifies whether to check the existence of the row before data is written. Default value: IGNORE. Valid values:

  • IGNORE: The row existence is not checked.

  • EXPECT_EXIST: The row is expected to exist.

  • EXPECT_NOT_EXIST: The row is expected not to exist.

return_content

ReturnContent

No

The data type after the row is successfully written. Only the primary key can be returned. In most cases, this parameter is used by the auto-increment primary key column feature.

transaction_id

string

No

The ID of the local transaction. This parameter is required if you use the local transaction feature to read data.

Response syntax

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

Parameter

Type

Description

consumed

ConsumedCapacity

The number of capacity units (CUs) consumed by the operation. For more information about CU consumption, see CU consumption.

row

bytes

The data that is returned when return_content is specified. If return_content is not specified or no return value exists, NULL is returned.

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

Use Tablestore SDKs

You can write a single row of data by using the following Tablestore SDKs:

CU consumption

  • If the row to which you want to write data does not exist, the number of consumed CUs varies based on the value that you specified for the condition parameter.

    • If the value of the condition parameter is IGNORE, the number of consumed write CUs is rounded up from the value that is calculated by using the following formula: Number of consumed write CUs = (Size of data in all primary key columns of the row + Size of data in the attribute columns to which you want to write data)/4 KB.

    • If the value of the condition parameter is EXPECT_NOT_EXIST, both write and read CUs are consumed. The number of consumed write CUs is rounded up from the value that is calculated by using the following formula: Number of consumed write CUs = (Size of data in all primary key columns of the row + Size of data in the attribute columns to which you want to write data)/4 KB. The number of consumed read CUs is rounded up from the value that is calculated by using the following formula: Number of consumed read CUs = Size of data in all primary key columns of the row/4 KB.

    • If the value of the condition parameter is EXPECT_EXIST, data fails to be written to the row. One write CU and one read CU are consumed.

  • If the row to which you want to write data exists, the number of consumed CUs varies based on the value that you specified for the condition parameter.

    • If the value of the condition parameter is IGNORE, the number of consumed write CUs is rounded up from the value that is calculated by using the following formula: Number of consumed write CUs = (Size of data in all primary key columns of the row + Size of data in the attribute columns to which you want to write data)/4 KB.

    • If the value of the condition parameter is EXPECT_EXIST, both write and read CUs are consumed. The number of consumed write CUs is rounded up from the value that is calculated by using the following formula: Number of consumed write CUs = (Size of data in all primary key columns of the row + Size of data in the attribute columns to which you want to write data)/4 KB. The number of consumed read CUs is rounded up from the value that is calculated by using the following formula: Number of consumed read CUs = Size of data in all primary key columns of the row/4 KB.

    • If the value of the condition parameter is EXPECT_NOT_EXIST, data fails to be written to the row. One write CU and one read CU are consumed.

    For more information about how to calculate the data size, see Billing overview.

  • When you use conditional update, the number of consumed CUs is calculated by using the preceding formulas if the operation succeeds. If the operation fails, one write CU and one read CU are consumed.

  • If the request times out and the results are undefined, CUs may or may not be consumed.

  • If an internal error occurs and the HTTP status code 5xx is returned, the operation does not consume CUs. If other errors occur, one write CU is consumed.