PutRow

Last Updated: Dec 04, 2017

Action:

This API inserts data in the specified row. If this row does not exist, a new row is added. If the row exists, the original row is overwritten.

Request message structure:

  1. message PutRowRequest {
  2. required string table_name = 1;
  3. required bytes row = 2; // The Plainbuffer encoding is binary
  4. required Condition condition = 3;
  5. optional ReturnContent return_content = 4;
  6. }

table_name:

  • Type: String

  • Required parameter: Yes

  • The name of the table to write data to.

row:

  • Type: Bytes

  • Required parameter: Yes

  • The data to be written into the row. It is in Plainbuffer format and includes the primary key and attribute column. For details about encoding, see Plainbuffer encoding.

condition:

  • Type: Condition

  • Required parameter: Yes

  • Determines whether to perform row existence check before writing data. There are three values:

    • IGNORE indicates that the row existence check is not performed.

    • EXPECT_EXIST indicates that the row is expected to exist.

    • EXPECT_NOT_EXIST indicates that the row is not expected to exist.

  • If the row is not expected to exist but it does, insertion will fail and an error will be returned. If the row is expected to exist but it does not, insertion will also fail and an error will be returned.

return_content:

  • Type: ReturnContent

  • Required parameter: No

  • The data type after the row is successfully written. Currently, only the primary key can be returned, which is used for the auto-increment function of the primary key column.

Response message structure:

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

consumed:

Capacity unit consumption:

  • If this row does not exist:

    • If the value of the specified condition check is IGNORE, the number of consumed write capacity units is the sum of the size of the primary key of the row and the size of the attribute column to be inserted divided by 4 KB and rounded up.

    • If the value of the specified condition check is EXPECT_NOT_EXIST, both write capacity units and read capacity units are consumed. The number of consumed write capacity units is the sum of the size of the primary key of the row and the size of the attribute column to be inserted divided by 4 KB and rounded up, and the number of consumed read capacity units is the size of the primary key of the row divided by 4 KB and rounded up.

    • If the value of the specified condition check is EXPECT_EXIST, insertion of the row will fail, which consumes one write capacity unit and one read capacity unit.

  • If this row exists:

    • If the value of the specified condition check is IGNORE, the number of consumed write capacity units is the sum of the size of the primary key of the row and the size of the attribute column to be inserted divided by 4 KB and rounded up.

    • If the value of the specified condition check is EXPECT_EXIST, both write capacity units and read capacity units are consumed. The number of consumed write capacity units is the sum of the size of the primary key of the row and the size of the attribute column to be inserted divided by 4 KB and rounded up, and the number of consumed read capacity units is the size of the primary key of the row divided by 4 KB and rounded up.

    • If the value of the specified condition check is EXPECT_NOT_EXIST, insertion of the row will fail, which consumes one write capacity unit and one read capacity unit.

  • Conditional Update:

    • If the operation succeeds, the consumed capacity units are calculated according to the preceding method.

    • If the operation fails, one write capacity unit and one read capacity unit are consumed.

      For details about how to calculate the data size, see Billing.

  • If an internal error code is returned (HTTP status code: 5XX), this operation will not consume capacity units. If other errors are returned, one write capacity unit will be consumed.

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

row:

  • Type: Bytes

  • The returned data when return_content is set.

  • If return_content is not set or there is no returned value, NULL is returned.

  • It is in Plainbuffer format. For details about encoding, see Plainbuffer encoding.

Thank you! We've received your feedback.