只有满足条件时,才能对数据表中的数据进行更新;当不满足条件时,更新失败并给用户报错。

前提条件

  • 已初始化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);