Table Store Node.js SDK 條件更新 - Tablestore

本文介紹如何在 Node.js SDK 中使用條件更新，設定更新條件後，只有目標行資料滿足指定的條件，才能完成更新。

前提條件

功能說明

條件更新的建構函式定義如下：

TableStore.Condition = inherit({
    constructor: function (rowExistenceExpectation, columnCondition)
    
    // other method
});

參數說明

rowExistenceExpectation（必選）TableStore.RowExistenceExpectation：行存在性條件，包括以下三種類型。
- IGNORE：不做行存在性判斷。
- EXPECT_EXIST：資料表中存在目標行資料時滿足條件，否則不滿足。
- EXPECT_NOT_EXIST：資料表中不存在目標行資料時滿足條件，否則不滿足。

columnCondition（可選）TableStore.ColumnCondition：列值判斷條件，包括以下兩種類型。

TableStore.SingleColumnCondition：判斷單個屬性列的值是否滿足條件。參數說明如下：

名稱	類型	說明
comparator（必選）	TableStore.ComparatorType	關係運算子，包括 EQUAL（等於）、NOT_EQUAL（不等於）、GREATER_THAN（大於）、GREATER_EQUAL（大於等於）、LESS_THAN（小於）、LESS_EQUAL（小於等於）。
columnName（必選）	string	判斷的屬性列名稱。
columnValue（必選）	STRING，INTEGER，BINARY，DOUBLE，BOOLEAN	判斷的值。
passIfMissing（可選）	boolean	行資料不包含目標屬性列時，是否滿足條件，預設值為 true，即行資料不包含目標屬性列時滿足條件，否則不滿足。
latestVersionOnly（可選）	boolean	是否只判斷最新的資料版本，預設值為 true，即當目標屬性列存在多個資料版本時，只判斷最新的資料版本是否符合判斷條件；如果為 false，則任一資料版本符合即視為滿足條件。

TableStore.CompositeCondition：判斷行資料是否滿足組合判斷條件。參數說明如下：

名稱

類型

說明

combinator（必選）

TableStore.LogicalOperator

邏輯運算子，包括 NOT（非）、AND（與）、OR（或）。

sub_conditions（必選）

Array

參與邏輯運算的子條件列表。

子條件可以是 TableStore.SingleColumnCondition 或 TableStore.CompositeCondition。
最多支援 32 個條件的組合。

範例程式碼

以下範例程式碼以 updateRow 方法為例介紹如何設定條件更新。

var params = {
    tableName: 'test_condition',
    primaryKey: [{ 'id': 'row1' }],
    updateOfAttributeColumns: [
        { 'PUT': [{ 'col1': 'changed_val1' }] }
    ]
};
// 構造更新條件（目標行資料在資料表中存在時才進行資料更新）
params.condition = new TableStore.Condition(TableStore.RowExistenceExpectation.EXPECT_EXIST, null)

// 調用 updateRow 方法更新行資料
client.updateRow(params, function (err, data) {
    if (err) {
        console.log('Update row failed with error:', err);
        return;
    }
    
    // 返回結果處理
    console.log('RequestId:', data.RequestId);
    console.log('Read CU Cost:', data.consumed.capacityUnit.read);
    console.log('Write CU Cost:', data.consumed.capacityUnit.write);
});

設定列值判斷條件，判斷單個屬性列的值是否滿足條件。

// col1 列的值等於 val1 時才進行資料更新
var singleColumnCondition = new TableStore.SingleColumnCondition('col1', 'val1', TableStore.ComparatorType.EQUAL)
params.condition = new TableStore.Condition(TableStore.RowExistenceExpectation.EXPECT_EXIST, singleColumnCondition)

設定列值判斷條件，對多個條件進行判斷。

// 設定組合條件 1
var compositeCondition1 = new TableStore.CompositeCondition(TableStore.LogicalOperator.AND);
// 添加子條件
compositeCondition1.addSubCondition(new TableStore.SingleColumnCondition('col1', 'val1', TableStore.ComparatorType.EQUAL));
compositeCondition1.addSubCondition(new TableStore.SingleColumnCondition('col2', 'val2', TableStore.ComparatorType.EQUAL));
// 設定組合條件 2
var compositeCondition2 = new TableStore.CompositeCondition(TableStore.LogicalOperator.OR);
compositeCondition2.addSubCondition(compositeCondition1);
compositeCondition2.addSubCondition(new TableStore.SingleColumnCondition('col3', 'val3', TableStore.ComparatorType.EQUAL));
// 添加組合條件，判斷條件為(col1 = val1 and col2 = val2) or (col3 = val3)
params.condition = new TableStore.Condition(TableStore.RowExistenceExpectation.EXPECT_EXIST, compositeCondition2)

情境案例

以下範例程式碼使用條件更新功能類比樂觀鎖的 CAS 實現。

async function optimisticLocking() {
    try {
        // 讀取原屬性列的值
        const getRowParams = {
            tableName: 'test_condition',
            primaryKey: [{ 'id': 'row1' }],
            maxVersions: 1,
            // 指定讀取的屬性列
            columnsToGet: ['col1']
        };
        const getRowResponse = await client.getRow(getRowParams);
        const oldValue = getRowResponse.row.attributes[0].columnValue;

        // 更新資料
        const updateRowParams = {
            tableName: 'test_condition',
            primaryKey: [{ 'id': 'row1' }],
            updateOfAttributeColumns: [
                { 'PUT': [{ 'col1': 'changed_val1' }] }
            ]
        }
        // 構造更新條件，目標屬性列最新版本的值等於預期值（讀取到的值）時，才進行更新
        const singleColumnCondition = new TableStore.SingleColumnCondition('col1', oldValue, TableStore.ComparatorType.EQUAL, true, true);
        updateRowParams.condition = new TableStore.Condition(TableStore.RowExistenceExpectation.EXPECT_EXIST, singleColumnCondition);
        const updateRowResponse = await client.updateRow(updateRowParams);

        // 返回結果處理
        console.log('RequestId:', updateRowResponse.RequestId);
        console.log('Read CU Cost:', updateRowResponse.consumed.capacityUnit.read);
        console.log('Write CU Cost:', updateRowResponse.consumed.capacityUnit.write);
    } catch (err) {
        console.log('Failed with error: ', err);
    }
}

optimisticLocking()