Table Store Python SDK 原子計數器 - Tablestore

使用 Python SDK 對整型屬性列執行行級原子的遞增或遞減操作。

前提條件

安裝Tablestore Python SDK並初始化用戶端。原子計數器需要 5.1.0 及以上版本，建議使用最新版本。

功能說明

調用 update_row 方法，將屬性列更新類型設定為 INCREMENT，對整型屬性列執行原子計數。正數表示遞增，負數表示遞減。

def update_row(
    self,
    table_name,
    row,
    condition,
    return_type=None,
    transaction_id=None,
)

以下樣本將 counter 屬性列的值原子增加 5。

primary_key = [("partition", "device"), ("id", 1)]
attribute_columns = {"INCREMENT": [("counter", 5)]}
row = Row(primary_key, attribute_columns)
condition = Condition(RowExistenceExpectation.EXPECT_EXIST)

consumed, return_row = client.update_row(
    "example_table",
    row,
    condition,
)
print("Write CU: %s" % consumed.write)

Python SDK 的 update_row 方法不直接返回原子計數後的列值。如需擷取新值，更新完成後調用 get_row 讀取該列。

參數說明

原子計數操作包含以下關鍵參數。

名稱	類型	說明
table_name（必選）	`str`	資料表名稱。
primary_key（必選）	`List[Tuple]`	目標行的主鍵。必須包含全部主鍵列，且主鍵結構與資料表一致。
column_name（必選）	`str`	執行原子計數的屬性列名稱。只支援整型屬性列。
value（必選）	`int`	屬性列值的變更量。正數遞增，負數遞減。
condition（必選）	`Condition`	更新條件。有關配置方法，請參見條件更新。
transaction_id（可選）	`str`	局部事務 ID。僅在局部事務內執行原子計數時設定。

使用限制

只支援整型屬性列。目標列不存在時，以 0 為初始值執行變更；目標列存在但不是整型時，返回 OTSParameterInvalid 錯誤。
變更量可為正數或負數，但計算結果不能超出 64 位元有符號整數範圍，否則返回 OTSParameterInvalid 錯誤。
原子計數只作用於最新版本，不支援指定資料版本號碼。更新後會寫入一個新的資料版本。
同一次更新中，不能對同一屬性列同時執行原子計數和覆蓋寫入、刪除等其他動作。

重要
原子計數操作可能因網路逾時或系統錯誤返回失敗。直接重試可能導致計數器被重複更新，使結果偏多或偏少。對精確性有嚴格要求時，先讀取當前值，再通過條件更新寫入新值。