You can use the conditional update feature to update data in a data table only if the specified conditions are met. If the conditions are not met, the update fails.
For information about the errors that may occur when you use the conditional update feature, see Error codes.
Prerequisites
An OTSClient instance is initialized. For more information, see Initialize an OTSClient instance.
A data table is created and data is written to the data table.
Usage notes
When you call 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 if the conditions are met.
Conditional update can be performed based on row existence conditions and column-based conditions.
Row existence conditions include IGNORE, EXPECT_EXIST, and EXPECT_NOT_EXIST.
When you modify a data table, Tablestore 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 CompositeCondition, which are used to determine whether the conditions are met based on the values of one or more columns.
Column-based conditions support the following relational operators: =, !=, >, >=, <, and <=. Column-based conditions also support the following logical operators: NOT, AND, and OR. You can specify up to 10 column-based conditions for a conditional update.
SingleColumnCondition supports comparison between a constant and a column. The column can be a primary key column. SingleColumnCondition does not support comparison between two columns and two constants.
Logical operators are used to combine subconditions in CompositeCondition. The subconditions can be SingleColumnCondition or CompositeCondition.
You can use conditional update to perform optimistic locking. When you update a row, you must obtain the value of a specific column and specify a row update condition based on the column value. For example, when you update the value of Column A in a row to 2, you must obtain the value of Column A. In this example, the obtained value is 1. Then, you must specify that the row can be updated only if the value of Column A is 1. If the specified condition is met, the update is successful. If the row is updated by another client, the update fails.
Parameters
Parameter | Description |
RowExistenceExpectation | The row existence condition. When you modify a table, Tablestore 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.
|
column_name | The name of the column. |
column_value | The comparison value of the column. |
comparator | The relational operator that is used to compare column values. For more 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 more 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. The number of subconditions that you can specify varies based on the logical operator that you use.
|
pass_if_missing | Specifies whether to pass the condition check when a column does not exist in a row. Type: Boolean. Valid values:
|
latest_version_only | Specifies whether to use only the latest version of values for comparison when a column has multiple versions of values. Type: Boolean. Valid values:
|
Examples
The following sample code provides an example on how to configure the conditional update feature to update a row of data based on the specified primary key. In this example, the update is successful only if the row exists and the value of the age column is 20. If the row does not exist or the value of the age column is not 20, the update fails.
def update_row_with_condition(client):
table_name = "<TABLE_NAME>"
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 is successful only if the following 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 if the row exists.
consumed, return_row = client.update_row(table_name, row, condition)