文档

条件更新

更新时间:

只有当数据满足列判断条件时,才能对数据表中的数据进行更新;当数据不满足列判断条件时,数据更新失败。

前提条件

使用方法

在通过PutRowUpdateRowDeleteRowBatchWriteRow接口操作表中数据时,您可以使用条件更新检查行存在性条件和列条件。只有当数据满足列判断条件时,才能对数据表中的数据进行更新。

条件更新中的列判断条件包括列条件和行存在性条件。

  • 列条件

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

    列条件中支持使用关系运算(=、!=、>、>=、<、<=)和逻辑运算(NOT、AND、OR),单个更新条件中最多支持设置10个列条件。

    • SingleColumnValueCondition支持一列和一个常量比较。不支持两列或者两个常量相比较。

    • CompositeColumnValueCondition的内节点为逻辑运算,子条件可以是SingleColumnValueCondition或CompositeColumnValueCondition。

  • 行存在性条件

    对数据表进行更改操作时,系统会先检查行存在性条件,如果不满足行存在性条件,则更改失败并给用户报错。

    行存在性条件包括IGNORE(忽略)、EXPECT_EXIST(期望存在)和EXPECT_NOT_EXIST(期望不存在)三种类型。

参数

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

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

当只有行存在性条件时,可以简写为如下结构。

    'condition' => <RowExistenceExpectation>    

SingleColumnValueCondition和CompositeColumnValueFilter结构如下。

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时,如果列存在多个版本的数据时,则会使用该列的所有版本的值进行比较,此时只要有一个版本的值满足条件,就条件检查通过,该行满足更新条件。

示例

根据行存在性条件操作数据

以下示例用于根据指定主键操作一行数据,如果指定的行存在,则操作成功,否则操作失败。

$request = array (
    'tables' => array (
        array (
            'table_name' => '<My_Table>',
            'rows' => array (  
                array (
                    //PUT操作
                    'operation_type' => OperationTypeConst::CONST_PUT,
                    //期望行不存在,如果该行不存在,则满足条件。
                    'condition' => RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST,
                    'primary_key' => array (
                        array('PK1', 'PrimaryKey'),
                        array('PK2', 11),
                    ),
                    'attribute_columns' => array (
                        array('attr1', 'Tablestore'),
                        array('attr2', 128)
                    )
                ),

                array (
                    //UPDATE操作
                    'operation_type' => OperationTypeConst::CONST_UPDATE,
                    //期望行存在,如果该行存在,则满足条件。
                    'condition' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,
                    'primary_key' => array (
                        array('PK1', 'PrimaryKey'),
                        array('PK2', 22),
                    ),
                    'update_of_attribute_columns'=> array(
                        'PUT' => array (
                            array('attr1', 'OTS'),
                            array('attr2',  256)
                        )
                    )
                ),
                
                array (
                    //DELETE操作
                    'operation_type' => OperationTypeConst::CONST_DELETE, 
                    //忽略,不做任何存在性检查。
                    'condition' => RowExistenceExpectationConst::CONST_IGNORE,
                    'primary_key' => array (
                        array('PK1', 'PrimaryKey'),
                        array('PK2', 33),
                    )
                ),
            )
        )
    )
);

$response = $otsClient->batchWriteRow ($request);

// 处理返回的每个表
foreach ($response['tables'] as $tableData) {
    print "Handling table {$tableData['table_name']} ...\n";
    
    // 处理这个表下的PutRow返回的结果
    $putRows = $tableData['rows'];
    
    foreach ($putRows as $rowData) {
      
      if ($rowData['is_ok']) {
        // 写入成功
        print "Capacity Unit Consumed: {$rowData['consumed']['capacity_unit']['write']}\n";
      } else {
        // 处理出错
        print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
      }
    }
  }

根据行条件和列条件操作数据

以下示例用于根据行条件和列条件操作数据。

$request = array (
    'tables' => array (
        array (
            'table_name' => 'MyTable',
            'rows' => array (  
                //SingleColumnValueCondition结构
                  array (
                    //UPDATE操作
                    'operation_type' => OperationTypeConst::CONST_UPDATE,
                    'condition' => array (
                        'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,
                        //attr2 != 256
                        'column_condition' => array (
                            'column_name' => 'attr2',
                            'value' => 256,
                            'comparator' => ComparatorTypeConst::CONST_NOT_EQUAL
                        )
                    ),
                    'primary_key' => array (
                        array('PK1', 'PrimaryKey'),
                        array('PK2', 11)
                    ),
                    // 用 attribute_columns/put 指定要更新或者追加的列,
                    'update_of_attribute_columns'=> array(
                        'PUT' => array (
                            array('attr1', 'OTS'),
                            array('attr2',  128)
                        )
                    )
                ),

                //CompositeColumnValueFilter结构
                array ( 
                    //UPDATE操作
                    'operation_type' => OperationTypeConst::CONST_UPDATE,
                    'condition' => array (
                        'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,
                        // attr1 = 'Tablestore' and attr2 >= 256
                        'column_condition' => array (
                            'logical_operator' => LogicalOperatorConst::CONST_AND,
                            'sub_conditions' => array (
                                array (
                                    'column_name' => 'attr2',
                                    'value' => 256,
                                    'comparator' => ComparatorTypeConst::CONST_GREATER_EQUAL
                                ),
                                array (
                                    'column_name' => 'attr1',
                                    'value' => 'Tablestore',
                                    'comparator' => ComparatorTypeConst::CONST_EQUAL
                                )
                            )
                        )
                    ),
                    'primary_key' => array (
                        array('PK1', 'pkValue'),
                        array('PK2', 22)
                    ),
                    'update_of_attribute_columns'=> array(
                        'PUT' => array (),
                        // 用 attribute_columns/delete 指定要删除的列
                        'DELETE_ALL' => array(
                            'attr1',
                            'attr2'
                        )
                    )
                ),
            )
        )
    )
);

$response = $otsClient->batchWriteRow ($request);

// 处理返回的每个表
foreach ($response['tables'] as $tableData) {
    print "Handling table {$tableData['table_name']} ...\n";
    
    // 处理这个表下的PutRow返回的结果
    $putRows = $tableData['rows'];
    
    foreach ($putRows as $rowData) {
      
      if ($rowData['is_ok']) {
        // 写入成功
        print "Capacity Unit Consumed: {$rowData['consumed']['capacity_unit']['write']}\n";
      } else {
        // 处理出错
        print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
      }
    }
  }

通过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);

更多代码示例,请参见PutRow@GitHubUpdateRow@GitHubDeleteRow@GitHubBatchWriteRow@GitHub