Use conditional updates - Tablestore SDK for Python - Tablestore

Use Tablestore SDK for Python to add conditions to row put, update, or delete operations so that an operation runs only if the target row meets the conditions.

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Function description

Use Condition to specify a row existence condition and an attribute column value condition. Pass the condition to put_row, update_row, delete_row, or the corresponding batch row operation. If the condition is not met, the server returns an error and does not modify the row.

Condition(row_existence_expectation, column_condition=None)

The following example updates the status attribute column only if the target row exists.

primary_key = [("partition", "device"), ("id", 1)]
row = Row(primary_key, {"PUT": [("status", "online")]})
condition = Condition(RowExistenceExpectation.EXPECT_EXIST)

consumed, return_row = client.update_row(
    "example_table",
    row,
    condition,
)

Parameters

Update condition

Condition contains the following parameters.

Name	Type	Description
row_existence_expectation (required)	`RowExistenceExpectation`	The row existence condition. `IGNORE` skips the row existence check. `EXPECT_EXIST` is met if the row exists. `EXPECT_NOT_EXIST` is met if the row does not exist.
column_condition (optional)	`ColumnCondition`	The attribute column value condition. `SingleColumnCondition`, `SingleColumnRegexCondition`, and `CompositeColumnCondition` are supported.

Single-column value condition

Call SingleColumnCondition(column_name, column_value, comparator, pass_if_missing=True, latest_version_only=True) to create a single-column value condition.

Name	Type	Description
column_name (required)	`str`	The name of the attribute column to evaluate.
column_value (required)	`str`, `int`, `bytes`, `float`, or `bool`	The target value. Its type must match the attribute column value type.
comparator (required)	`ComparatorType`	The comparison operator. Valid values are `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, and `LESS_EQUAL`.
pass_if_missing (optional)	`bool`	Specifies whether the condition is met if the target attribute column is missing. Default value: `True`. If this parameter is `False`, the condition is not met when the column is missing.
latest_version_only (optional)	`bool`	Specifies whether to evaluate only the latest version. Default value: `True`. If this parameter is `False`, the condition is met if any version matches.

Single-column regular expression condition

Call SingleColumnRegexCondition(column_name, comparator, column_value=None, regex_rule=None, latest_version_only=True) to create a single-column regular expression condition. Only string attribute columns support regular expression conditions.

Name	Type	Description
column_name (required)	`str`	The name of the string attribute column to evaluate.
comparator (required)	`ComparatorType`	The comparison operator. Valid values are `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_EQUAL`, `LESS_THAN`, `LESS_EQUAL`, `EXIST`, and `NOT_EXIST`.
column_value (optional)	`str`, `int`, or `float`	The target value. Omit this parameter if `comparator` is `EXIST` or `NOT_EXIST`. Otherwise, this parameter is required. If `regex_rule` is omitted, the type must match the attribute column value type. If `regex_rule` is specified, the type must match `regex_rule.cast_type`.
regex_rule (optional)	`RegexRule`	The substring extraction and type conversion rule. If this parameter is omitted, the attribute column value is compared directly.
latest_version_only (optional)	`bool`	Specifies whether to evaluate only the latest version. Default value: `True`. If this parameter is `False`, the condition is met if any version matches.

If the target attribute column is missing, a single-column regular expression condition is never met. pass_if_missing cannot be configured separately for this condition.

Regular expression rule

The regex_rule parameter is of the RegexRule type and contains the following parameters.

Name	Type	Description
regex_input (required)	`str`	The regular expression, up to 256 bytes. Perl-compatible expressions and single-byte characters are supported. Chinese characters are not supported. If the expression contains capturing groups, the first group is extracted. Otherwise, the entire match is extracted.
cast_type (required)	`CastType`	The type to which the extracted value is converted. Valid values are `VT_STRING`, `VT_INTEGER`, and `VT_DOUBLE`. The condition is not met if the extracted value cannot be converted.

Composite column value condition

Call CompositeColumnCondition(combinator) to create a composite column value condition, and then call add_sub_condition to add conditions.

Name	Type	Description
combinator (required)	`LogicalOperator`	The logical operator. Valid values are `AND`, `OR`, and `NOT`.
sub_conditions (required)	`List[ColumnCondition]`	The conditions to combine. Single-column value conditions, single-column regular expression conditions, and nested composite conditions are supported, with a maximum of 32 conditions.

Examples

Use a single-column value condition

The following example updates data only if the target row exists and the latest value of the status attribute column is pending. The condition is not met if the column is missing.

column_condition = SingleColumnCondition(
    "status",
    "pending",
    ComparatorType.EQUAL,
    pass_if_missing=False,
)
condition = Condition(
    RowExistenceExpectation.EXPECT_EXIST,
    column_condition,
)

client.update_row("example_table", row, condition)

Combine column value conditions

The following example constructs the condition (status == "pending" AND revision == 1) OR priority > 5.

status_and_revision = CompositeColumnCondition(LogicalOperator.AND)
status_and_revision.add_sub_condition(
    SingleColumnCondition("status", "pending", ComparatorType.EQUAL)
)
status_and_revision.add_sub_condition(
    SingleColumnCondition("revision", 1, ComparatorType.EQUAL)
)

column_condition = CompositeColumnCondition(LogicalOperator.OR)
column_condition.add_sub_condition(status_and_revision)
column_condition.add_sub_condition(
    SingleColumnCondition("priority", 5, ComparatorType.GREATER_THAN)
)
condition = Condition(RowExistenceExpectation.EXPECT_EXIST, column_condition)

Implement optimistic locking with CAS

The following example reads the current revision value and uses it as an update condition. The revision is incremented only if another request has not modified the data.

primary_key = [("partition", "device"), ("id", 1)]
consumed, current_row, next_token = client.get_row(
    "example_table",
    primary_key,
    columns_to_get=["revision"],
)
old_revision = current_row.attribute_columns[0][1]

row = Row(primary_key, {"PUT": [("revision", old_revision + 1)]})
column_condition = SingleColumnCondition(
    "revision",
    old_revision,
    ComparatorType.EQUAL,
    pass_if_missing=False,
    latest_version_only=True,
)
condition = Condition(RowExistenceExpectation.EXPECT_EXIST, column_condition)

client.update_row("example_table", row, condition)