Table Store Java SDK 條件更新 - Tablestore

前提條件

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

功能說明

Condition 包含行存在性條件（rowExistenceExpectation）和列值判斷條件（columnCondition），兩者可獨立設定或組合使用。通過 RowPutChange、RowUpdateChange 或 RowDeleteChange 的 setCondition 方法設定條件；這些行變更對象也可加入 BatchWriteRow 請求。條件不滿足時，服務端返回錯誤且不修改行資料。

rowChange.setCondition(condition)
new SingleColumnValueCondition(columnName, operator, columnValue)
new CompositeColumnValueCondition(logicOperator)

以下樣本對資料表 condition_demo 中主鍵 row1 的行執行更新，僅當該行存在時才更新（行不存在則返回錯誤）。

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

RowUpdateChange rowUpdateChange = new RowUpdateChange("condition_demo", primaryKey);
rowUpdateChange.put("col1", ColumnValue.fromString("changed_val1"));

Condition condition = new Condition();
condition.setRowExistenceExpectation(RowExistenceExpectation.EXPECT_EXIST);
rowUpdateChange.setCondition(condition);

client.updateRow(new UpdateRowRequest(rowUpdateChange));

參數說明

更新條件

Condition 包含以下參數。行存在性條件和列值條件可獨立設定或組合使用；當 rowExistenceExpectation 為 IGNORE 且未設定 columnCondition 時，不執行條件判斷。

名稱

類型

說明

rowExistenceExpectation（可選）

RowExistenceExpectation

行存在性條件，取值包括：

IGNORE（預設）：不做行存在性判斷。
EXPECT_EXIST：資料表中存在目標行資料時滿足條件，否則不滿足。
EXPECT_NOT_EXIST：資料表中不存在目標行資料時滿足條件，否則不滿足。

columnCondition（可選）

ColumnCondition

列值判斷條件，子類包括 SingleColumnValueCondition（單列值判斷）和 CompositeColumnValueCondition（組合判斷）。

單列值判斷

Condition.columnCondition 使用 SingleColumnValueCondition 時，包含以下參數。

名稱	類型	說明
columnName（必選）	String	判斷的屬性列名稱。
operator（必選）	CompareOperator	關係運算子，取值包括： `EQUAL`（等於） `NOT_EQUAL`（不等於） `GREATER_THAN`（大於） `GREATER_EQUAL`（大於等於） `LESS_THAN`（小於） `LESS_EQUAL`（小於等於）
columnValue（必選）	ColumnValue	判斷的值。
passIfMissing（可選）	boolean	行資料不包含目標屬性列時是否視為滿足條件。預設 `true`（視為滿足）。設定為 `false` 時，行不包含目標列即視為不滿足。
latestVersionsOnly（可選）	boolean	是否只判斷最新的資料版本。預設 `true`（只判斷最新版本）。設定為 `false` 時，任意版本符合條件即視為滿足。

組合條件

Condition.columnCondition 使用 CompositeColumnValueCondition 時，包含以下參數。通過 addCondition() 添加子條件，最多支援 32 個條件。

名稱

類型

說明

type（必選）

LogicOperator

邏輯運算子，取值包括：

AND（與），至少添加兩個子條件。
OR（或），至少添加兩個子條件。
NOT（非），只能添加一個子條件。

conditions（必選）

List<ColumnCondition>

參與邏輯運算的子條件列表，通過 addCondition() 添加。子條件可以是 SingleColumnValueCondition 或 CompositeColumnValueCondition（支援嵌套）。

情境樣本

單列值條件

通過 SingleColumnValueCondition 判斷單個屬性列值。以下樣本對主鍵 row1 的行更新 col2，僅當 col1 == "changed_val1" 時才執行。

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

RowUpdateChange rowUpdateChange = new RowUpdateChange("condition_demo", primaryKey);
rowUpdateChange.put("col2", ColumnValue.fromString("new_val2"));

Condition condition = new Condition();
SingleColumnValueCondition singleCondition = new SingleColumnValueCondition(
        "col1",
        SingleColumnValueCondition.CompareOperator.EQUAL,
        ColumnValue.fromString("changed_val1"));
condition.setColumnCondition(singleCondition);
rowUpdateChange.setCondition(condition);

client.updateRow(new UpdateRowRequest(rowUpdateChange));

組合列值條件

通過 CompositeColumnValueCondition 用邏輯運算子組合多個條件，支援嵌套。以下樣本構造條件 (col1 == "changed_val1" AND col2 == "new_val2") OR (col3 == "val3")。

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

RowUpdateChange rowUpdateChange = new RowUpdateChange("condition_demo", primaryKey);
rowUpdateChange.put("col1", ColumnValue.fromString("final_val1"));

// 子條件：col1 == "changed_val1" AND col2 == "new_val2"
CompositeColumnValueCondition andCondition = new CompositeColumnValueCondition(
        CompositeColumnValueCondition.LogicOperator.AND);
andCondition.addCondition(new SingleColumnValueCondition(
        "col1",
        SingleColumnValueCondition.CompareOperator.EQUAL,
        ColumnValue.fromString("changed_val1")));
andCondition.addCondition(new SingleColumnValueCondition(
        "col2",
        SingleColumnValueCondition.CompareOperator.EQUAL,
        ColumnValue.fromString("new_val2")));

// 頂層 OR：(col1 AND col2) OR (col3)
CompositeColumnValueCondition orCondition = new CompositeColumnValueCondition(
        CompositeColumnValueCondition.LogicOperator.OR);
orCondition.addCondition(andCondition);
orCondition.addCondition(new SingleColumnValueCondition(
        "col3",
        SingleColumnValueCondition.CompareOperator.EQUAL,
        ColumnValue.fromString("val3")));

Condition condition = new Condition();
condition.setColumnCondition(orCondition);
rowUpdateChange.setCondition(condition);

client.updateRow(new UpdateRowRequest(rowUpdateChange));

防止並發覆蓋

利用條件更新實現 Compare-and-Swap：先讀取原值，再用讀到的值作為更新條件。僅當列值仍等於讀到的值時才執行更新；若期間有其他進程修改了該列，本次更新失敗，確保不覆蓋未讀到的並發修改。

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

// 1. 讀取原值
SingleRowQueryCriteria queryCriteria = new SingleRowQueryCriteria("condition_demo", primaryKey);
queryCriteria.setMaxVersions(1);
GetRowResponse getResponse = client.getRow(new GetRowRequest(queryCriteria));
String oldValue = getResponse.getRow().getLatestColumn("col1").getValue().asString();

// 2. 基於讀到的舊值做條件更新（只有 col1 仍等於 oldValue 時才更新）
RowUpdateChange rowUpdateChange = new RowUpdateChange("condition_demo", primaryKey);
rowUpdateChange.put("col1", ColumnValue.fromString("cas_updated"));

Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
SingleColumnValueCondition casCondition = new SingleColumnValueCondition(
        "col1",
        SingleColumnValueCondition.CompareOperator.EQUAL,
        ColumnValue.fromString(oldValue));
casCondition.setPassIfMissing(false);
casCondition.setLatestVersionsOnly(true);
condition.setColumnCondition(casCondition);
rowUpdateChange.setCondition(condition);

client.updateRow(new UpdateRowRequest(rowUpdateChange));