全部产品
阿里云办公

条件更新

更新时间:2018-07-02 09:22:07

条件更新功能是指只有在满足条件时才对表中的数据进行更改,当不满足条件时更新失败,可用于 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”。若更新失败,代表有其他客户端已经成功更新了该行。

格式

  1. 'condition' => [
  2. 'row_existence' => <RowExistenceExpectation>
  3. 'column_condition' => <ColumnCondition>
  4. ]

其中 SingleColumnValueCondition 结构如下

  1. [
  2. 'column_name' => '<string>',
  3. 'value' => <ColumnValue>,
  4. 'comparator' => <ComparatorType>
  5. 'pass_if_missing' => true || false
  6. 'latest_version_only' => true || false
  7. ]

CompositeColumnValueCondition结构如下

  1. [
  2. 'logical_operator' => <LogicalOperator>
  3. 'sub_conditions' => [
  4. <ColumnCondition>,
  5. <ColumnCondition>,
  6. <ColumnCondition>,
  7. // other conditions
  8. ]
  9. ]

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

  1. '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。

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

示例 2

构造 CompositeColumnValueCondition。

  1. // composite1 条件为 (Col0 == 0) AND (Col1 > 100)
  2. $composite1 = [
  3. 'logical_operator' => LogicalOperatorConst::CONST_AND,
  4. 'sub_conditions' => [
  5. [
  6. 'column_name' => 'Col0',
  7. 'value' => 0,
  8. 'comparator' => ComparatorTypeConst::CONST_EQUAL
  9. ],
  10. [
  11. 'column_name' => 'Col1',
  12. 'value' => 100,
  13. 'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
  14. ]
  15. ]
  16. ];
  17. // composite2 条件为 ( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)
  18. $composite2 = [
  19. 'logical_operator' => LogicalOperatorConst::CONST_OR,
  20. 'sub_conditions' => [
  21. $composite1,
  22. [
  23. 'column_name' => 'Col2',
  24. 'value' => 10,
  25. 'comparator' => ComparatorTypeConst::CONST_LESS_EQUAL
  26. ]
  27. ]
  28. ];

示例 3

通过Condition可以实现乐观锁机制,下面例子演示如何通过Condition实现特定列递增功能。

  1. // 读一行
  2. $request = [
  3. 'table_name' => 'MyTable',
  4. 'primary_key' => [ // 主键
  5. ['PK0', 123],
  6. ['PK1', 'abc']
  7. ],
  8. 'max_versions' => 1
  9. ];
  10. $response = $otsClient->getRow ($request);
  11. $columnMap = getColumnValueAsMap($response['attribute_columns']);
  12. $col0Value = $columnMap['col0'][0][1];
  13. // 条件更新Col0这一列, 使列值+1
  14. $request = [
  15. 'table_name' => 'MyTable',
  16. 'condition' => [
  17. 'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,
  18. 'column_condition' => [ //条件更新,满足则更新
  19. 'column_name' => 'col0',
  20. 'value' => $col0Value,
  21. 'comparator' => ComparatorTypeConst::CONST_EQUAL
  22. ]
  23. ],
  24. 'primary_key' => [ // 主键
  25. ['PK0', 123],
  26. ['PK1', 'abc']
  27. ],
  28. 'update_of_attribute_columns'=> [
  29. 'PUT' => [
  30. ['col0', $col0Value+1]
  31. ]
  32. ]
  33. ];
  34. $response = $otsClient->updateRow ($request);