Prérequis
Le client a été initialisé. Pour plus d'informations, consultez la rubrique Initialiser le client Tablestore.
Une table de données a été créée et des données y ont été écrites. Pour plus d'informations, consultez la rubrique Créer une table de données.
Description
Le conteneur Condition contient une condition d'existence de ligne (rowExistenceExpectation), une condition de colonne (columnCondition), ou les deux. Transmettez la condition configurée à la méthode setCondition() sur les objets RowPutChange, RowUpdateChange ou RowDeleteChange. Ces modifications de ligne peuvent également être incluses dans une requête BatchWriteRow. Si la condition n'est pas remplie, le serveur renvoie une erreur et la ligne reste inchangée.
rowChange.setCondition(condition)
new SingleColumnValueCondition(columnName, operator, columnValue)
new CompositeColumnValueCondition(logicOperator)L'exemple suivant met à jour la ligne dont la clé primaire est row1 dans la table condition_demo uniquement si la ligne existe. Dans le cas contraire, le serveur renvoie une erreur.
PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"))
.build();
RowUpdateChange rowUpdateChange = new RowUpdateChange("condition_demo", primaryKey);
rowUpdateChange.put("col1", ColumnValue.fromString("changed_val1"));
Condition condition = new Condition();
condition.setRowExistenceExpectation(RowExistenceExpectation.EXPECT_EXIST);
rowUpdateChange.setCondition(condition);
client.updateRow(new UpdateRowRequest(rowUpdateChange));Paramètres
Les mises à jour conditionnelles peuvent servir de condition pour les opérations PutRow, UpdateRow, DeleteRow et BatchWriteRow.
'condition' => [
'row_existence' => <RowExistenceExpectation>
'column_condition' => <ColumnCondition>
] Si seule une condition d'existence de ligne est spécifiée, vous pouvez utiliser la structure abrégée suivante.
'condition' => <RowExistenceExpectation> Les structures pour SingleColumnValueCondition et CompositeColumnValueCondition sont présentées ci-dessous.
Structure SingleColumnValueCondition
[
'column_name' => '<string>',
'value' => <ColumnValue>,
'comparator' => <ComparatorType>,
'pass_if_missing' => true || false,
'latest_version_only' => true || false
]Structure CompositeColumnValueFilter
[
'logical_operator' => <LogicalOperator>
'sub_conditions' => [
<ColumnCondition>,
<ColumnCondition>,
<ColumnCondition>,
// other conditions
]
]Paramètre | Description |
row_existence | Lorsque vous modifiez une table de données, le système vérifie d'abord la condition d'existence de la ligne. Si la condition n'est pas remplie, la modification échoue et une erreur est signalée. Les conditions d'existence de ligne incluent IGNORE, EXPECT_EXIST et EXPECT_NOT_EXIST. Elles sont représentées par RowExistenceExpectationConst::CONST_IGNORE, RowExistenceExpectationConst::CONST_EXPECT_EXIST et RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST.
|
column_name | Le nom de la colonne. |
value | La valeur à comparer avec la colonne. Le format est [Valeur, Type]. Le type peut être INTEGER, STRING (encodé en UTF-8), BINARY, BOOLEAN ou DOUBLE. Ces types sont représentés par ColumnTypeConst::CONST_INTEGER, ColumnTypeConst::CONST_STRING, ColumnTypeConst::CONST_BINARY, ColumnTypeConst::CONST_BOOLEAN et ColumnTypeConst::CONST_DOUBLE. Le type est obligatoire pour BINARY. Pour les autres valeurs, le type est facultatif. Si le type n'est pas BINARY, vous pouvez utiliser le format abrégé Valeur. |
comparator | L'opérateur relationnel utilisé pour comparer la valeur de la colonne. Pour plus d'informations sur le type, consultez ComparatorType. Les opérateurs relationnels incluent EQUAL (=), NOT_EQUAL (!=), GREATER_THAN (>), GREATER_EQUAL (>=), LESS_THAN (<) et LESS_EQUAL (<=). Ils sont représentés par ComparatorTypeConst::CONST_EQUAL, ComparatorTypeConst::CONST_NOT_EQUAL, ComparatorTypeConst::CONST_GREATER_THAN, ComparatorTypeConst::CONST_GREATER_EQUAL, ComparatorTypeConst::CONST_LESS_THAN et ComparatorTypeConst::CONST_LESS_EQUAL. |
logical_operator | L'opérateur logique utilisé pour combiner plusieurs conditions. Pour plus d'informations sur le type, consultez LogicalOperator. Les opérateurs logiques incluent NOT, AND et OR. Ils sont représentés par LogicalOperatorConst::CONST_NOT, LogicalOperatorConst::CONST_AND et LogicalOperatorConst::CONST_OR. Le nombre de sous-conditions que vous pouvez ajouter dépend de l'opérateur logique.
|
pass_if_missing | Indique si la vérification de la condition réussit lorsque la colonne n'existe pas dans une ligne. Le type est booléen. La valeur par défaut est true. Cela signifie que si la colonne n'existe pas dans une ligne, la vérification de la condition réussit et la ligne satisfait la condition de mise à jour. Si vous définissez pass_if_missing sur false, la vérification de la condition échoue lorsque la colonne n'existe pas dans une ligne. La ligne ne satisfait pas la condition de mise à jour. |
latest_version_only | Indique s'il faut utiliser uniquement la dernière version de la valeur de la colonne pour la comparaison si la colonne possède plusieurs versions. Le type est booléen. La valeur par défaut est true. Cela signifie que si la colonne possède plusieurs versions, seule la dernière version est utilisée pour la comparaison. Si vous définissez latest_version_only sur false et que la colonne possède plusieurs versions, toutes les versions de la valeur de la colonne sont utilisées pour la comparaison. Dans ce cas, si une version quelconque satisfait la condition, la vérification de la condition réussit et la ligne satisfait la condition de mise à jour. |
Exemples
Effectuer des opérations de données basées sur des conditions d'existence de ligne
L'exemple suivant montre comment effectuer une opération sur une ligne en fonction de sa clé primaire et d'une condition d'existence de ligne spécifiée.
$request = array (
'tables' => array (
array (
'table_name' => 'my_table',
'rows' => array (
array (
// PUT operation
'operation_type' => OperationTypeConst::CONST_PUT,
// Expects the row to not exist. The condition is met if the row does not exist.
'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
'operation_type' => OperationTypeConst::CONST_UPDATE,
// Expects the row to exist. The condition is met if the row exists.
'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
'operation_type' => OperationTypeConst::CONST_DELETE,
// Ignore. No existence check is performed.
'condition' => RowExistenceExpectationConst::CONST_IGNORE,
'primary_key' => array (
array('PK1', 'PrimaryKey'),
array('PK2', 33),
)
),
)
)
)
);
$response = $otsClient->batchWriteRow ($request);
// Process the response for each table
foreach ($response['tables'] as $tableData) {
print "Handling table {$tableData['table_name']} ...\n";
// Process the PutRow results for this table
$putRows = $tableData['rows'];
foreach ($putRows as $rowData) {
if ($rowData['is_ok']) {
// The write operation is successful
print "Capacity Unit Consumed: {$rowData['consumed']['capacity_unit']['write']}\n";
} else {
// An error occurred
print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
}
}
}Effectuer des opérations de données basées sur des conditions de ligne et de colonne
L'exemple suivant montre comment effectuer une opération basée sur des conditions de ligne et de colonne.
$request = array (
'tables' => array (
array (
'table_name' => 'MyTable',
'rows' => array (
// SingleColumnValueCondition structure
array (
// UPDATE operation
'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)
),
// Use attribute_columns/put to specify the columns to update or append.
'update_of_attribute_columns'=> array(
'PUT' => array (
array('attr1', 'OTS'),
array('attr2', 128)
)
)
),
// CompositeColumnValueFilter structure
array (
// UPDATE operation
'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 (),
// Use attribute_columns/delete to specify the columns to delete.
'DELETE_ALL' => array(
'attr1',
'attr2'
)
)
),
)
)
)
);
$response = $otsClient->batchWriteRow ($request);
// Process the response for each table
foreach ($response['tables'] as $tableData) {
print "Handling table {$tableData['table_name']} ...\n";
// Process the PutRow results for this table
$putRows = $tableData['rows'];
foreach ($putRows as $rowData) {
if ($rowData['is_ok']) {
// The write operation is successful
print "Capacity Unit Consumed: {$rowData['consumed']['capacity_unit']['write']}\n";
} else {
// An error occurred
print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
}
}
}Utiliser une condition pour implémenter le verrouillage optimiste et incrémenter une colonne
L'exemple suivant montre comment créer une condition pour implémenter le verrouillage optimiste et incrémenter une colonne.
// Read a row of data.
$request = [
'table_name' => 'MyTable',
'primary_key' => [ // Primary key.
['PK0', 123],
['PK1', 'abc']
],
'max_versions' => 1
];
$response = $otsClient->getRow ($request);
$columnMap = getColumnValueAsMap($response['attribute_columns']);
$col0Value = $columnMap['col0'][0][1];
// Conditionally update the col0 column to increment its value by 1.
$request = [
'table_name' => 'MyTable',
'condition' => [
'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,
'column_condition' => [ // If the condition is met, update the data.
'column_name' => 'col0',
'value' => $col0Value,
'comparator' => ComparatorTypeConst::CONST_EQUAL
]
],
'primary_key' => [ // Primary key.
['PK0', 123],
['PK1', 'abc']
],
'update_of_attribute_columns'=> [
'PUT' => [
['col0', $col0Value+1]
]
]
];
$response = $otsClient->updateRow ($request);Pour plus d'exemples de code, consultez PutRow@GitHub, UpdateRow@GitHub, DeleteRow@GitHub et BatchWriteRow@GitHub.