指定された条件が満たされた場合にのみ、条件付き更新機能を使用してデータテーブルのデータを更新できます。条件が満たされない場合、更新は失敗します。
前提条件
OTSClient インスタンスが初期化されていること。詳細については、OTSClient インスタンスを初期化するを参照してください。
データテーブルが作成され、データがデータテーブルに書き込まれていること。詳細については、データテーブルを作成するを参照してください。
使用上の注意
PutRow、UpdateRow、DeleteRow、または BatchWriteRow 操作を呼び出してデータテーブルのデータを更新する場合、行の有無条件と列ベースの条件を指定して条件付き更新を実行できます。データテーブルのデータは、条件が満たされた場合にのみ更新されます。
条件付き更新には、行の有無条件と列ベースの条件を指定できます。
列ベースの条件
列ベースの条件には、SingleColumnValueConditions と CompositeColumnValueConditions が含まれ、1 つ以上の列の値に基づいて条件ベースの判断を実行するために使用されます。列ベースの条件は、Tablestore フィルターで使用される条件に似ています。
列ベースの条件では、=, !=, >, >=, <, <= NOT, AND, OR などの関係演算子と論理演算子がサポートされています。条件付き更新には、最大 10 個の列ベースの条件を指定できます。
SingleColumnValueCondition を使用すると、列を定数と比較できます。SingleColumnValueCondition では、2 つの列または 2 つの定数の比較はサポートされていません。
CompositeColumnValueCondition は、複数の SingleColumnValueConditions または CompositeColumnValueConditions で構成されます。サブ条件間の論理関係を指定する必要があります。
行の有無条件
データテーブルを更新すると、Tablestore は最初に、行の有無条件が満たされているかどうかを確認します。行の有無条件が満たされていない場合、更新は失敗し、エラーが報告されます。
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 | 行の有無条件。データテーブルを変更すると、Tablestore は行の有無条件を確認します。行の有無条件が満たされていない場合、変更は失敗し、エラーが報告されます。 行の有無条件には、IGNORE、EXPECT_EXIST、EXPECT_NOT_EXIST があります。Tablestore では、RowExistenceExpectationConst::CONST_IGNORE は IGNORE を、RowExistenceExpectationConst::CONST_EXPECT_EXIST は EXPECT_EXIST を、RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST は EXPECT_NOT_EXIST を指定します。
|
column_name | 列の名前。 |
value | 列の比較値。 このパラメーターの値は [Value, Type] 形式です。型として Integer、String、Binary、Boolean、または Double を指定できます。Tablestore では、ColumnTypeConst::CONST_INTEGER は Integer 値を、ColumnTypeConst::CONST_STRING は UTF-8 エンコードされた文字列を、ColumnTypeConst::CONST_BINARY は Binary 値を、ColumnTypeConst::CONST_BOOLEAN は Boolean 値を、ColumnTypeConst::CONST_DOUBLE は Double 値を指定します。型が Binary の場合、値と型を指定する必要があります。 型が Binary でない場合、型を指定せずに値を指定できます。 |
comparator | 列値の比較に使用する関係演算子。関係演算子の種類の詳細については、ComparatorType を参照してください。 関係演算子には、EQUAL(=), NOT_EQUAL(!=), GREATER_THAN(>), GREATER_EQUAL(>=), LESS_THAN(<), LESS_EQUAL(<=) があります。Tablestore では、ComparatorTypeConst::CONST_EQUAL は EQUAL(=) を、ComparatorTypeConst::CONST_NOT_EQUAL は NOT_EQUAL(!=) を、ComparatorTypeConst::CONST_GREATER_THAN は GREATER_THAN(>) を、ComparatorTypeConst::CONST_GREATER_EQUAL は GREATER_EQUAL(>=) を、ComparatorTypeConst::CONST_LESS_THAN は LESS_THAN(<) を、ComparatorTypeConst::CONST_LESS_EQUAL は LESS_EQUAL(<=) を指定します。 |
logical_operator | 複数の条件を組み合わせるために使用する論理演算子。論理演算子の種類の詳細については、LogicalOperator を参照してください。 論理演算子には、NOT、AND、OR があります。Tablestore では、LogicalOperatorConst::CONST_NOT は NOT を、LogicalOperatorConst::CONST_AND は AND を、LogicalOperatorConst::CONST_OR は OR を指定します。 指定できるサブ条件の数は、使用する論理演算子によって異なります。
|
pass_if_missing | 行に列が存在しない場合に条件チェックをパスするかどうかを指定します。このパラメーターの値はブール型です。デフォルト値は true で、行に列が存在しない場合、条件チェックに合格し、行は更新条件を満たします。 pass_if_missing パラメーターを false に設定し、行に列が存在しない場合、条件チェックは失敗し、行は更新条件を満たしません。 |
latest_version_only | 列に複数のバージョンのデータがある場合、比較に最新バージョンのデータのみを使用するかどうかを指定します。このパラメーターの値はブール型です。デフォルト値は true で、列に複数のバージョンのデータがある場合、比較には最新バージョンのデータのみが使用されます。 latest_version_only パラメーターを false に設定し、列に複数のバージョンのデータがある場合、すべてのバージョンのデータが比較に使用されます。この場合、1 つのバージョンのみが条件を満たしている場合、条件チェックに合格し、行は更新条件を満たします。 |
例
行の有無条件に基づいてデータに対する操作を実行する
次のサンプルコードは、行のプライマリキーに基づいてデータの行に対する操作を実行する方法の例を示しています。この例では、指定された行が存在する場合、操作は成功します。それ以外の場合、操作は失敗します。
$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 // 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 // attr1 = 'Tablestore' かつ 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";
}
}
}列の値を増やすためにオプティミスティックロックを実行する条件を構築する
次のサンプルコードは、列の値を増やすためにオプティミスティックロックを実行する条件を構築する方法の例を示しています。
// データの行を読み取ります。
$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 増やすために、Col0 列の条件付き更新を設定します。
$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 を参照してください。