If you use conditional update, data in the table can be updated only when the conditions are met. If the conditions are not met, the update fails.

Note For more information about errors that may occur when you use conditional update, see Error codes.

Prerequisites

  • The OTSCclient is initialized. For more information, see Initialization.
  • A data table is created. Data is written to the table.

Usage notes

When you use the PutRow, UpdateRow, DeleteRow, or BatchWriteRow operation to update data, you can use conditional update to check row existence conditions and column-based conditions. The update is successful only when the conditions are met.

Conditional update includes row existence conditions and column-based conditions.

  • Row existence conditions: include IGNORE, EXPECT_EXIST, and EXPECT_NOT_EXIST.

    When you modify a table, the system first checks the row existence condition. If the row existence condition is not met, the modification fails, and an error is reported.

  • Column-based conditions: include SingleColumnCondition and CompositeColumnCondition, which are used to determine whether the conditions are met based on the values of one or more columns.
    • SingleColumnCondition supports the comparison between a constant and a column that can be a primary key column. SingleColumnCondition does not support the comparison between two columns or two constants.
    • The inner node of CompositeColumnCondition is used to perform logical operations. Subconditions can be SingleColumnCondition or CompositeColumnCondition.

Conditional update can be used to implement optimistic locking. When you update a row, the value of the specified column is obtained. Assume that Column A has a value of 1. Obtain the value in Column A and set a condition that the value in Column A is 1. Update the value in Column A to 2. If the update fails, the row is updated by another client.

Limits

Column-based conditions for conditional update support relational operators such as =, !=, >, >=, <, and <=, and logical operators such as NOT, AND, and OR. You can specify up to 10 conditions.

Parameters

Parameter Description
RowExistenceExpectation The row existence condition. When you modify a table, Tablestore first checks the row existence condition. If the row existence condition is not met, the modification fails and an error is reported.

Row existence conditions include IGNORE, EXPECT_EXIST, and EXPECT_NOT_EXIST. In Tablestore, RowExistenceExpectation_IGNORE indicates IGNORE, RowExistenceExpectation_EXPECT_EXIST indicates EXPECT_EXIST, and RowExistenceExpectation_EXPECT_NOT_EXIST indicates EXPECT_NOT_EXIST.

  • IGNORE: No existence check is performed.
  • EXPECT_EXIST: The row is expected to exist. If the row exists, the condition is met. If the row does not exist, the condition is not met.
  • EXPECT_NOT_EXIST: The row is expected not to exist. If the row does not exist, the condition is met. If the row exists, the condition is not met.
column_name The name of the column.
column_value The compare value of the column.
comparator The relational operator that is used to compare column values. For information, see ComparatorType.

Relational operators include EQUAL(=), NOT_EQUAL(!=), GREATER_THAN(>), GREATER_EQUAL(>=), LESS_THAN(<), and LESS_EQUAL(<=). In Tablestore, CT_EQUAL indicates EQUAL(=), CT_NOT_EQUAL indicates NOT_EQUAL(!=), CT_GREATER_THAN indicates GREATER_THAN(>), CT_GREATER_EQUAL indicates GREATER_EQUAL(>=), CT_LESS_THAN indicates LESS_THAN(<), and CT_LESS_EQUAL indicates LESS_EQUAL(<=).

combinator The logical operator that is used to combine multiple conditions. For information, see LogicalOperator.

Logical operators include NOT, AND, and OR. In Tablestore, LO_NOT indicates NOT, LO_AND indicates AND, and LO_OR indicates OR.

Different logical operators require different numbers of subconditions.
  • When the logical operator is NOT, only one subcondition can be added.
  • When the logical operator is AND or OR, you must add at least two subconditions.
pass_if_missing Specifies whether to pass the condition check when the column does not exist in a row. The type of this parameter value is Boolean. The default value is True, which indicates that if the column does not exist in a row, the condition check is passed, and the row meets the update conditions.

When pass_if_missing is set to False, the condition check fails if the column does not exist in a row. In this case, the row does not meet the update conditions.

latest_version_only Specifies whether to use only the value of the latest version when the column has multiple versions of values. The type of this parameter value is Boolean. The default value is True, which indicates that if the column has multiple versions of values, only the value of the latest version is used for comparison.

When latest_version_only is set to False, if the column has multiple versions of values, the values of all versions are used for comparison. In this case, if the value of a version meets the condition, the condition check is passed, and the row meets the update conditions.

Example

Update a row based on the specified primary key. If the specified row exists and the value of the age column in the specified row is 20, the update succeeds. Otherwise, the update fails. 

primary_key = [('gid',1), ('uid',"101")]
update_of_attribute_columns = {
    'PUT' : [('name','David'), ('address','Hongkong')],
    'DELETE' : [('address', None, 1488436949003)],
    'DELETE_ALL' : [('mobile'), ('age')],
    'INCREMENT' : [('counter', -1)]
}
row = Row(primary_key, update_of_attribute_columns)

# Specify that the update succeeds only when the following two conditions are met. Otherwise, the update fails. 
# (1) The specified row exists. 
# (2) The value of the age column in the specified row is 20. 
condition = Condition(RowExistenceExpectation.EXPECT_EXIST, SingleColumnCondition("age", 20, ComparatorType.EQUAL)) # Update the row only when this row exists. 

consumed, return_row = client.update_row(table_name, row, condition)