表格存储 Python SDK 条件更新 - 表格存储

使用 Python SDK 为行写入、更新或删除操作设置判断条件，仅在目标行满足条件时执行操作。

前提条件

功能说明

通过 Condition 设置行存在性条件和属性列值条件，并将其传入 put_row、update_row、delete_row 或相应的批量行操作。条件不满足时，服务端返回错误，行数据不被修改。

Condition(row_existence_expectation, column_condition=None)

以下示例仅在目标行存在时更新 status 属性列。

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,
)

参数说明

更新条件

Condition 包含以下参数。

名称	类型	说明
row_existence_expectation（必选）	`RowExistenceExpectation`	行存在性条件。`IGNORE` 表示不判断行是否存在；`EXPECT_EXIST` 表示行存在时满足条件；`EXPECT_NOT_EXIST` 表示行不存在时满足条件。
column_condition（可选）	`ColumnCondition`	属性列值条件。支持 `SingleColumnCondition`、`SingleColumnRegexCondition` 和 `CompositeColumnCondition`。

单列值条件

调用 SingleColumnCondition(column_name, column_value, comparator, pass_if_missing=True, latest_version_only=True) 创建单列值条件。

名称	类型	说明
column_name（必选）	`str`	待判断的属性列名称。
column_value（必选）	`str`、`int`、`bytes`、`float`、`bool`	用于比较的目标值。类型必须与属性列值一致。
comparator（必选）	`ComparatorType`	比较运算符。取值为 `EQUAL`、`NOT_EQUAL`、`GREATER_THAN`、`GREATER_EQUAL`、`LESS_THAN` 或 `LESS_EQUAL`。
pass_if_missing（可选）	`bool`	行中不存在目标属性列时是否满足条件，默认值为 `True`。设置为 `False` 时，缺少该列即不满足条件。
latest_version_only（可选）	`bool`	是否只判断属性列的最新版本，默认值为 `True`。设置为 `False` 时，任一版本符合即满足条件。

单列正则条件

调用 SingleColumnRegexCondition(column_name, comparator, column_value=None, regex_rule=None, latest_version_only=True) 创建单列正则条件。只有字符串类型的属性列支持正则条件。

名称	类型	说明
column_name（必选）	`str`	待判断的字符串属性列名称。
comparator（必选）	`ComparatorType`	比较运算符。取值为 `EQUAL`、`NOT_EQUAL`、`GREATER_THAN`、`GREATER_EQUAL`、`LESS_THAN`、`LESS_EQUAL`、`EXIST` 或 `NOT_EXIST`。
column_value（可选）	`str`、`int`、`float`	用于比较的目标值。`comparator` 为 `EXIST` 或 `NOT_EXIST` 时必须不设置，其他情况下必须设置。不设置 `regex_rule` 时，类型必须与属性列值一致；设置时，类型必须与 `regex_rule.cast_type` 一致。
regex_rule（可选）	`RegexRule`	正则提取和类型转换规则。不设置时直接比较属性列值。
latest_version_only（可选）	`bool`	是否只判断属性列的最新版本，默认值为 `True`。设置为 `False` 时，任一版本符合即满足条件。

行中不存在目标属性列时，单列正则条件始终不满足，无法单独配置 pass_if_missing。

正则规则

regex_rule 的类型为 RegexRule，包含以下参数。

名称	类型	说明
regex_input（必选）	`str`	正则表达式，长度不超过 256 字节。支持 Perl 正则和单字节字符，不支持匹配中文。包含捕获分组时提取第一个分组；不包含分组时提取整个匹配结果。
cast_type（必选）	`CastType`	提取结果的转换类型。取值为 `VT_STRING`、`VT_INTEGER` 或 `VT_DOUBLE`。转换失败时不满足条件。

组合列值条件

调用 CompositeColumnCondition(combinator) 创建组合列值条件，再调用 add_sub_condition 添加子条件。

名称	类型	说明
combinator（必选）	`LogicalOperator`	逻辑运算符。取值为 `AND`、`OR` 或 `NOT`。
sub_conditions（必选）	`List[ColumnCondition]`	参与逻辑运算的子条件。支持单列值条件、单列正则条件和嵌套的组合条件，最多组合 32 个条件。

场景示例

单列值条件

以下示例仅在目标行存在且 status 属性列的最新值为 pending 时更新数据。目标列不存在时不满足条件。

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)

组合列值条件

以下示例构造 (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)

乐观锁 CAS

以下示例先读取 revision 的当前值，再以该值作为更新条件。只有数据未被其他请求修改时，版本号才加 1。

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)