Table Store Python SDK 條件更新 - Tablestore

使用 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`	Regex，長度不超過 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)