Table Store Java SDK 原子計數器 - Tablestore

前提條件

安裝 Tablestore Java SDK並初始化用戶端。

功能說明

調用 increment(Column) 對指定整型列執行原子計數：正數表示遞增，負數表示遞減。服務端在行層級保證操作的原子性，並在更新完成後寫入一個新的資料版本。如需在同一請求中擷取更新後的值，調用 addReturnColumn(String) 指定返回列，並將 returnType 設定為 RT_AFTER_MODIFY。

public UpdateRowResponse updateRow(UpdateRowRequest updateRowRequest) throws TableStoreException, ClientException
public RowUpdateChange increment(Column column)
public void addReturnColumn(String columnName)
public void setReturnType(ReturnType returnType)

以下樣本對資料表 counter_demo 中主鍵 pk0 的行執行 price 列遞增 10 操作，並在同一請求中讀取更新後的值。

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("pk0"))
        .build();

RowUpdateChange rowUpdateChange = new RowUpdateChange("counter_demo", primaryKey);

// 對 price 列執行遞增操作，加 10（負數表示遞減）
rowUpdateChange.increment(new Column("price", ColumnValue.fromLong(10)));

// 同一請求中返回更新後的列值
rowUpdateChange.addReturnColumn("price");
rowUpdateChange.setReturnType(ReturnType.RT_AFTER_MODIFY);

UpdateRowResponse response = client.updateRow(new UpdateRowRequest(rowUpdateChange));
Row row = response.getRow();
System.out.println("Updated price: " + row.getLatestColumn("price").getValue().asLong());

參數說明

請求配置

UpdateRowRequest 包含以下參數。

名稱

類型

說明

rowChange（必選）

RowUpdateChange

單行更新配置。

transactionId（可選）

String

局部事務 ID。僅在局部事務內執行原子計數時設定。

關於如何擷取和使用該 ID，請參見局部事務。

行更新配置

UpdateRowRequest.rowChange 的類型為 RowUpdateChange。

名稱	類型	說明
tableName（必選）	String	資料表名稱。
primaryKey（必選）	PrimaryKey	目標行的主鍵。
columnsToUpdate（必選）	List<Pair<Column, Type>>	要更新的屬性列。調用 `increment(Column)` 添加原子計數操作。
condition（可選）	Condition	條件更新配置。僅當目標行滿足條件時執行原子計數。關於條件的配置方法，請參見條件更新。
returnType（可選）	ReturnType	傳回型別。預設值為 `RT_NONE`；如需返回更新後的值，設定為 `RT_AFTER_MODIFY`。
returnColumnNames（可選）	Set<String>	要返回更新後值的原子計數列名稱。通過 `addReturnColumn()` 添加，並與 `RT_AFTER_MODIFY` 配合使用。

計數列

通過 increment() 添加到 UpdateRowRequest.rowChange.columnsToUpdate 的每個元素都包含一個 Column 對象。

名稱	類型	說明
name（必選）	String	執行原子計數的屬性列名稱。
value（必選）	ColumnValue	整型增量。正數表示遞增，負數表示遞減；計算結果不能溢出。目標列不存在時，以 0 為初始值執行計算。

傳回值

名稱	類型	說明
row	Row	設定 `RT_AFTER_MODIFY` 後，包含通過 `addReturnColumn()` 指定的原子計數列更新後值。通過 `getRow()` 擷取。

使用限制

目標列已存在但非整型時，返回 OTSParameterInvalid 錯誤。
原子計數操作只作用於最新版本，不支援指定時間戳記。
單次更新要求中，對同一列不能同時執行原子計數和其他動作（如覆蓋寫、刪除等）。
BatchWriteRow 請求中，已執行原子計數的行只能在批次中出現一次。

重要

原子計數操作可能因網路逾時、系統錯誤等失敗，重試時可能更新兩次原子計數器，導致計數偏多或偏少。此類異常情境建議使用條件更新精確變更列值。