條件更新 - Tablestore

只有滿足條件時，才能對資料表中的資料進行更新；當不滿足條件時，更新失敗並給使用者報錯。

前提條件

已初始化Client，詳情請參見初始化。
已建立資料表並寫入資料。

使用方法

在通過PutRow、UpdateRow、DeleteRow或BatchWriteRow介面更新資料時，可以使用條件更新檢查行存在性條件和列條件，只有滿足條件時才能更新成功。

條件更新包括行存在性條件和列條件。

行存在性條件：包括IGNORE、EXPECT_EXIST和EXPECT_NOT_EXIST，分別代表忽略、期望存在和期望不存在。
對資料表變更操作時，系統會先檢查行存在性條件，如果不滿足行存在性條件，則更改失敗並給使用者報錯。
列條件：包括SingleColumnValueCondition和CompositeColumnValueCondition，是基於某一列或者某些列的列值進行條件判斷。如果不滿足列條件，則更改失敗並給使用者報錯。
- SingleColumnValueCondition支援一列和一個常量比較。不支援兩列或者兩個常量相比較。
- CompositeColumnValueCondition的內節點為邏輯運算，子條件可以是SingleColumnValueCondition或CompositeColumnValueCondition。

條件更新可以實現樂觀鎖功能，即在更新某行時，先擷取某列的值，假設為列A，值為1，然後設定條件列A＝1，更新行使列A＝2。如果更新失敗，表示有其他用戶端已成功更新該行。

限制

條件更新的列條件支援關係運算（=、!=、>、>=、<、<=）和邏輯運算（NOT、AND、OR），最多支援10個條件的組合。

參數

條件更新可以用於PutRow、UpdateRow、DeleteRow和BatchWriteRow的condition中。

    'condition' => [
        'row_existence' => <RowExistenceExpectation>
        'column_condition' => <ColumnCondition>
    ]

當只有行存在性條件時，可以簡寫為如下結構。

    'condition' => <RowExistenceExpectation>

SingleColumnValueCondition結構

    [
        'column_name' => '<string>',
        'value' => <ColumnValue>,
        'comparator' => <ComparatorType>
        'pass_if_missing' => true || false
        'latest_version_only' => true || false
    ]

CompositeColumnValueFilter結構

    [
        'logical_operator' => <LogicalOperator>
        'sub_conditions' => [
            <ColumnCondition>,
            <ColumnCondition>,
            <ColumnCondition>,
            // other conditions
        ]
    ]


參數	說明
row_existence	對資料表變更操作時，系統會先檢查行存在性條件，如果不滿足行存在性條件，則更改失敗並給使用者報錯。行存在性條件包括IGNORE、EXPECT_EXIST和EXPECT_NOT_EXIST，分別用RowExistenceExpectationConst::CONST_IGNORE、RowExistenceExpectationConst::CONST_EXPECT_EXIST、RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST表示。 IGNORE：表示忽略，不做任何存在性檢查。 EXPECT_EXIST：表示期望存在，如果該行存在，則滿足條件；如果該行不存在，則不滿足條件。 EXPECT_NOT_EXIST：期望行不存在，如果該行不存在，則滿足條件；如果該行存在，則不滿足條件。
column_name	列的名稱。
value	列的對比值。格式為[Value, Type]。Type可以是INTEGER、STRING（UTF-8編碼字串）、BINARY、BOOLEAN、DOUBLE五種，分別用ColumnTypeConst::CONST_INTEGER、ColumnTypeConst::CONST_STRING、ColumnTypeConst::CONST_BINARY、ColumnTypeConst::CONST_BOOLEAN、ColumnTypeConst::CONST_DOUBLE表示，其中BINARY不可省略，其他類型均可省略。當Type不是BINARY時，可以簡寫為Value。
comparator	對列值進行比較的關係運算子，類型詳情請參見ComparatorType。關係運算子包括EQUAL（=）、NOT_EQUAL（!=）、GREATER_THAN（>）、GREATER_EQUAL（>=）、LESS_THAN（<）和LESS_EQUAL（<=），分別用ComparatorTypeConst::CONST_EQUAL、ComparatorTypeConst::CONST_NOT_EQUAL、ComparatorTypeConst::CONST_GREATER_THAN、ComparatorTypeConst::CONST_GREATER_EQUAL、ComparatorTypeConst::CONST_LESS_THAN、ComparatorTypeConst::CONST_LESS_EQUAL表示。
logical_operator	對多個條件進行組合的邏輯運算子，類型詳情請參見LogicalOperator。邏輯運算子包括NOT、AND和OR，分別用LogicalOperatorConst::CONST_NOT、LogicalOperatorConst::CONST_AND、LogicalOperatorConst::CONST_OR表示。邏輯運算子不同可以添加的子條件個數不同。當邏輯運算子為NOT時，只能添加一個子條件。當邏輯運算子為AND或OR時，必須至少添加兩個子條件。
pass_if_missing	當列在某行中不存在時，條件檢查是否通過。類型為bool值，預設值為true，表示如果列在某行中不存在時，則條件檢查通過，該行滿足更新條件。當設定pass_if_missing為false時，如果列在某行中不存在時，則條件檢查不通過，該行不滿足更新條件。
latest_version_only	當列存在多個版本的資料時，是否只使用最新版本的值做比較。類型為bool值，預設值為true，表示如果列存在多個版本的資料時，則只使用該列最新版本的值進行比較。當設定latest_version_only為false時，如果列存在多個版本的資料時，則會使用該列的所有版本的值進行比較，此時只要有一個版本的值滿足條件，就條件檢查通過，該行滿足更新條件。

樣本

構造SingleColumnValueCondition。

    //設定條件更新，當Col0的值為0時，條件檢查通過。
    $column_condition = [
        'column_name' => 'Col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL 
        'pass_if_missing' => false                         //如果不存在Col0列，條件檢查不通過。
        'latest_version_only' => true                      //只判斷最新版本。
    ];

構造CompositeColumnValueCondition。

//composite1的條件為(Col0 == 0) AND (Col1 > 100)。
    $composite1 = [
        'logical_operator' => LogicalOperatorConst::CONST_AND,
        'sub_conditions' => [
            [
                'column_name' => 'Col0',
                'value' => 0,
                'comparator' => ComparatorTypeConst::CONST_EQUAL
            ],
            [
                'column_name' => 'Col1',
                'value' => 100,
                'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
            ]
        ]
    ];
    //composite2的條件為( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)。
    $composite2 = [
        'logical_operator' => LogicalOperatorConst::CONST_OR,
        'sub_conditions' => [
            $composite1,
            [
                'column_name' => 'Col2',
                'value' => 10,
                'comparator' => ComparatorTypeConst::CONST_LESS_EQUAL
            ]
        ]
    ];

通過Condition實現樂觀鎖機制，遞增一列。

    //讀取一行資料。
    $request = [
        'table_name' => 'MyTable',
        'primary_key' => [ //主鍵。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'max_versions' => 1
    ];
    $response = $otsClient->getRow ($request);
    $columnMap = getColumnValueAsMap($response['attribute_columns']);
    $col0Value = $columnMap['col0'][0][1];
    //條件更新Col0列, 使列值加1。
    $request = [
        'table_name' => 'MyTable',
        'condition' => [
            'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,
            'column_condition' => [                  //滿足條件，則更新資料。
                'column_name' => 'col0',
                'value' => $col0Value,
                'comparator' => ComparatorTypeConst::CONST_EQUAL
            ]
        ],
        'primary_key' => [ //主鍵。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'update_of_attribute_columns'=> [
            'PUT' => [
                ['col0', $col0Value+1]
            ]
        ]
    ];
    $response = $otsClient->updateRow ($request);