只有當資料滿足列判斷條件時，才能對資料表中的資料進行更新；當資料不滿足列判斷條件時，資料更新失敗。
前提條件
已初始化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。