只有当数据满足列判断条件时，才能对数据表中的数据进行更新；当数据不满足列判断条件时，数据更新失败。
前提条件
已初始化Client。具体操作，请参见初始化OTSClient。
已创建数据表并写入数据。具体操作，请参见创建数据表。
使用方法
在通过PutRow、UpdateRow、DeleteRow和BatchWriteRow接口操作表中数据时，您可以使用条件更新检查行存在性条件和列条件。只有当数据满足列判断条件时，才能对数据表中的数据进行更新。
条件更新中的列判断条件包括列条件和行存在性条件。
列条件
目前支持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表示。
|
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表示。 逻辑运算符不同可以添加的子条件个数不同。
|
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@GitHub、UpdateRow@GitHub、DeleteRow@GitHub和BatchWriteRow@GitHub。