条件更新功能是指只有在满足条件时才对表中的数据进行更改,当不满足条件时更新失败,可用于 PutRow、UpdateRow、DeleteRow 和 BatchWriteRow 的condition 中。

判断条件包括行存在性条件和列条件。

  • 行存在性条件:分为 IGNORE、 EXPECT_EXIST 和 EXPECT_NOT_EXIST,分别代表忽略、期望存在和期望不存在。可以分别设置为RowExistenceExpectationConst::CONST_IGNORE、RowExistenceExpectationConst::CONST_EXPECT_EXIST和RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST。 在对表进行更改操作时,会首先检查行存在性条件。若不满足,则更改失败,对用户抛错。

  • 列条件:目前支持两种,SingleColumnValueCondition 和 CompositeColumnValueCondition。是基于某一列或者某些列的列值进行条件判断,与过滤器 Filter 中的条件非常类似。

基于条件更新可以实现乐观锁的功能,即在更新某行时,先获取某列的值。假设为列 A,值为 1,然后设置条件“列 A=1”,更新该行同时使“列 A=2”。若更新失败,代表有其他客户端已经成功更新了该行。

格式

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

其中 SingleColumnValueCondition 结构如下

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

CompositeColumnValueCondition结构如下

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

或者当只有行存在性条件时(大部分情况是这样),可以简写为:

    'condition' => <RowExistenceExpectation>
格式说明
  • row_existence 行存在性条件
    • 分为 IGNORE、 EXPECT_EXIST 和 EXPECT_NOT_EXIST,分别代表忽略、期望存在和期望不存在。
    • 可以分别设置为RowExistenceExpectationConst::CONST_IGNORE、RowExistenceExpectationConst::CONST_EXPECT_EXIST和RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST。
    • 在对表进行更改操作时,会首先检查行存在性条件。若不满足,则更改失败,对用户抛错。
  • column_condition 列条件,

    • SingleColumnValueCondition 支持一列(可以是主键列)和一个常量比较。不支持两列相比较,也不支持两个常量相比较。
      • 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 比较类型
        • EQUAL 表示相等,用 ComparatorTypeConst::CONST_EQUAL 表示
        • NOT_EQUAL 表示不相等,用 ComparatorTypeConst::CONST_NOT_EQUAL 表示
        • GREATER_THAN 表示大于,用 ComparatorTypeConst::CONST_GREATER_THAN 表示
        • GREATER_EQUAL 表示大于等于,用 ComparatorTypeConst::CONST_GREATER_EQUAL 表示
        • LESS_THAN 表示小于,用 ComparatorTypeConst::CONST_LESS_THAN 表示
        • LESS_EQUAL 表示小于等于,用 ComparatorTypeConst::CONST_LESS_EQUAL 表示
      • pass_if_missing 由于OTS一行的属性列不固定,有可能存在有condition条件的列在该行不存在的情况,这时参数控制在这种情况下对该行的检查结果。
        • 如果设置为true,则若列在该行中不存在,该节点即认为true。
        • 如果设置为false,则若列在该行中不存在,该节点即认为false。
        • 默认值为true。
      • latest_version_only 是否只对最新版本有效。
        • 如果为true,则表示只检测最新版本的值是否满足条件;
        • 如果是false,则会检测所有版本的值是否满足条件,任意一个列值满足条件,该节点即认为true。
        • 默认值为true。
    • CompositeColumnValueCondition 一个树形结构,内节点为逻辑运算(logical_operator),叶节点为比较判断SingleColumnValueCondition

      • logical_operator 逻辑操作符,枚举类型
        • NOT 表示非,用 LogicalOperatorConst::CONST_NOT 表示。
        • AND 表示并,用 LogicalOperatorConst::CONST_AND 表示。
        • OR 表示或,用 LogicalOperatorConst::CONST_OR 表示。
      • sub_conditions 递归下去, 可以继续是SingleColumnValueCondition 或 CompositeColumnValueCondition

        • 其中并和或可以挂载两个或更多子节点,非只能挂载一个子节点。

示例1

构造 SingleColumnValueCondition。

    // 设置过滤器, 当Col0的值为0时返回该行.
    $column_condition = [
        'column_name' => 'Col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL 
        'pass_if_missing' => false                         // 如果不存在Col0这一列, 也不返回.
        'latest_version_only' => true                      // 只判断最新版本
    ];

示例2

构造 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
            ]
        ]
    ];

示例3

通过Condition可以实现乐观锁机制,下面例子演示如何通过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);