Table Store Python SDK 局部事務 - Tablestore

使用 Python SDK 將同一分區索引值範圍內的多次讀寫組成一個原子操作，事務中的寫入全部提交或全部丟棄。

前提條件

安裝Tablestore Python SDK並初始化用戶端。
已為資料表開啟局部事務功能。

說明
如果需要為已有資料表開啟局部事務，或者確認資料表是否已開啟該功能，請提交工單。

功能說明

局部事務作用於一個分區索引值，隔離等級為讀已提交（Read Committed）。事務內的請求通過同一個事務 ID 關聯，按以下流程使用：

調用 start_local_transaction，傳入分區索引值並擷取事務 ID。
在事務內調用 get_row、put_row、update_row、delete_row、batch_write_row 或 get_range，並通過 transaction_id 攜帶事務 ID。
調用 commit_transaction 提交事務，使所有寫入生效；或者調用 abort_transaction 丟棄事務，使所有寫入失效。

def start_local_transaction(self, table_name, key)
def commit_transaction(self, transaction_id)
def abort_transaction(self, transaction_id)

以下樣本為分區索引值 device 建立局部事務，在事務內寫入一行資料，然後提交事務。

table_name = "example_table"
partition_key = [("partition", "device")]
transaction_id = client.start_local_transaction(table_name, partition_key)

primary_key = [("partition", "device"), ("id", 1)]
row = Row(primary_key, [("status", "online")])
condition = Condition(RowExistenceExpectation.IGNORE)
client.put_row(
    table_name,
    row,
    condition,
    transaction_id=transaction_id,
)

client.commit_transaction(transaction_id)

參數說明

局部事務包含以下關鍵參數。

名稱	類型	說明
table_name（必選）	`str`	資料表名稱。
key（必選）	`List[Tuple]`	建立局部事務時指定的分區鍵，只需包含第一個主鍵列的名稱和值。
primary_key（必選）	`List[Tuple]`	在事務內讀寫行時指定的完整主鍵，必須包含全部主鍵列。寫請求的分區索引值必須與 `key` 一致。
transaction_id（必選）	`str`	`start_local_transaction` 返回的局部事務 ID。事務內的每個讀寫請求以及提交或丟棄請求都需攜帶該 ID。

使用限制

主鍵自增列與局部事務不能同時使用。
局部事務通過悲觀鎖控制並發。事務期間，分區索引值對應的資料被加寫鎖，只有攜帶事務 ID 的寫請求可以成功。
事務生命週期最長為 60 秒。兩次操作間隔超過 60 秒時，事務逾時，服務端自動丟棄。
同一事務 ID 同一時間只能用於一個請求，並發使用該 ID 的請求均失敗。
事務內寫請求的分區索引值必須與建立事務時一致；讀請求沒有此限制。
單個事務最多寫入 4 MB 資料。
事務內寫入屬性列時，如果未指定資料版本號碼，服務端在寫入時產生版本號碼，而不是在提交時產生。
BatchWriteRowRequest 攜帶事務 ID 時，所有行只能操作該事務對應的資料表。
事務內沒有寫操作時，提交與丟棄效果相同，都會釋放事務。
攜帶事務 ID 的讀寫請求失敗不會結束事務。可以重試請求，或者主動丟棄事務。

情境樣本

事務內讀取一行

以下樣本在局部事務內讀取一行資料。對於唯讀事務，提交和丟棄效果相同。

table_name = "example_table"
partition_key = [("partition", "device")]
transaction_id = client.start_local_transaction(table_name, partition_key)

primary_key = [("partition", "device"), ("id", 1)]
consumed, return_row, next_token = client.get_row(
    table_name,
    primary_key,
    transaction_id=transaction_id,
)
print(return_row.primary_key, return_row.attribute_columns)

client.commit_transaction(transaction_id)

事務內批量寫入多行

以下樣本通過 set_transaction_id 在批量請求中攜帶事務 ID。所有行的分區索引值必須與建立事務時一致。

table_name = "example_table"
partition_key = [("partition", "device")]
transaction_id = client.start_local_transaction(table_name, partition_key)

condition = Condition(RowExistenceExpectation.IGNORE)
row_items = [
    PutRowItem(Row([("partition", "device"), ("id", 2)], [("status", "online")]), condition),
    PutRowItem(Row([("partition", "device"), ("id", 3)], [("status", "offline")]), condition),
]
request = BatchWriteRowRequest()
request.add(TableInBatchWriteRowItem(table_name, row_items))
request.set_transaction_id(transaction_id)

response = client.batch_write_row(request)
if response.is_all_succeed():
    client.commit_transaction(transaction_id)
else:
    client.abort_transaction(transaction_id)