Writes data to a specified 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 succeeds.

Request syntax

message PutRowRequest {
    required string table_name = 1;
    required bytes row = 2; // The data is encoded as binary code in the PlainBuffer format.
    required Condition condition = 3;
    optional ReturnContent return_content = 4; 
}
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. Valid values:

  • IGNORE: The row existence check is not performed.

  • EXPECT_EXIST: The row is expected to exist.

  • EXPECT_NOT_EXIST: The row is not expected to exist.

return_content ReturnContent No

The type of data to return after data is written to the row. Only the primary key columns can be returned, which are used for the auto-increment feature of the primary key columns.

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 this request.

row bytes

  • The returned data when return_content is specified.

  • If return_content is not specified or no data is returned, NULL is returned.

  • For more information about PlainBuffer, see PlainBuffer.

CU consumption

  • If the specified row does not exist:

    • If the value of the condition parameter is IGNORE, the number of consumed write CUs is calculated and rounded up based on the following formula: Number of consumed write CUs = [(Size of the data in all the primary key columns of the row + Size of the data in the inserted attribute columns)/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 calculated and rounded up based on the following formula: Number of consumed write CUs = [(Size of the data in all the primary key columns of the row + Size of the data in the inserted attribute columns)/4 KB]. The number of consumed read CUs is calculated and rounded up based on the following formula: Number of consumed read CUs = Size of the data in all the 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 specified row exists:

    • If the value of the condition parameter is IGNORE, the number of consumed write CUs is calculated and rounded up based on the following formula: Number of consumed write CUs = [(Size of the data in all the primary key columns of the row + Size of the data in the inserted attribute columns)/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 calculated and rounded up based on the following formula: Number of consumed write CUs = [(Size of the data in all the primary key columns of the row + Size of the data in the inserted attribute columns)/4 KB]. The number of consumed read CUs is calculated and rounded up based on the following formula: Number of consumed read CUs = Size of the data in all the 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.

  • Conditional update:

    • If the request succeeds, the number of consumed CUs is calculated based on the preceding formulas.

    • If the request fails, one write CU and one read CU are consumed.

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

  • If an internal error (HTTP status code: 5xx) is returned, this request does not consume CUs. If other errors are returned, one write CU is consumed.

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