You can use the conditional update feature to update data in a data table only if the specified conditions are met. If the conditions are not met, the update fails.
Prerequisites
An OTSClient instance is initialized. For more information, see Initialize an OTSClient instance.
A data table is created and data is written to the data table. For more information, see Create a data table and Write data.
Usage notes
When you call the PutRow, UpdateRow, DeleteRow, or BatchWriteRow operation to update data, you can use conditional update to check row existence conditions and column-based conditions. The update is successful only if the conditions are met.
Conditional update can be performed based on row existence conditions and column-based conditions.
Row existence conditions include IGNORE, EXPECT_EXIST, and EXPECT_NOT_EXIST.
When you modify a data table, Tablestore first checks the row existence condition. If the row existence condition is not met, the modification fails and an error is reported.
Column-based conditions include SingleColumnCondition and CompositeCondition, which are used to determine whether the conditions are met based on the values of one or more columns.
Column-based conditions support the following relational operators: =, !=, >, >=, <, and <=. Column-based conditions also support the following logical operators: NOT, AND, and OR. You can specify up to 10 column-based conditions for a conditional update.
SingleColumnCondition supports comparison between a constant and a column. The column can be a primary key column. SingleColumnCondition does not support comparison between two columns and two constants.
Logical operators are used to combine subconditions in CompositeCondition. The subconditions can be SingleColumnCondition or CompositeCondition.
You can use conditional update to perform optimistic locking. When you update a row, you must obtain the value of a specific column and specify a row update condition based on the column value. For example, when you update the value of Column A in a row to 2, you must obtain the value of Column A. In this example, the obtained value is 1. Then, you must specify that the row can be updated only if the value of Column A is 1. If the specified condition is met, the update is successful. If the row is updated by another client, the update fails.
Parameters
Parameter | Description |
RowExistenceExpectation | The row existence condition. When you modify a table, Tablestore checks the row existence condition. If the row existence condition is not met, the modification fails and an error is reported. Row existence conditions include IGNORE, EXPECT_EXIST, and EXPECT_NOT_EXIST. In Tablestore, RowExistenceExpectation_IGNORE is used to specify IGNORE, RowExistenceExpectation_EXPECT_EXIST is used to specify EXPECT_EXIST, and RowExistenceExpectation_EXPECT_NOT_EXIST is used to specify EXPECT_NOT_EXIST.
|
columnName | The name of the column. |
columnValue | The comparison value of the column. |
comparator | The relational operator used to compare the column value. For information about the types of relational operators, see ComparatorType. Relational operators include EQUAL(=), NOT_EQUAL(!=), GREATER_THAN(>), GREATER_EQUAL(>=), LESS_THAN(<), and LESS_EQUAL(<=). In Tablestore, CT_EQUAL is used to specify EQUAL(=), CT_NOT_EQUAL is used to specify NOT_EQUAL(!=), CT_GREATER_THAN is used to specify GREATER_THAN(>), CT_GREATER_EQUAL is used to specify GREATER_EQUAL(>=), CT_LESS_THAN is used to specify LESS_THAN(<), and CT_LESS_EQUAL is used to specify LESS_EQUAL(<=). |
combinator | The logical operator that combines multiple conditions. For information about the types of logical operators, see LogicalOperator. Logical operators include NOT, AND, and OR. In Tablestore, LO_NOT is used to specify NOT, LO_AND is used to specify AND, and LO_OR is used to specify OR. The number of subconditions that you can specify varies based on the logical operator that you use.
|
passIfMissing | Specifies whether to pass the conditional check when a column does not exist in a row. The value of this parameter is of the Boolean type. The default value is true, which specifies that if the column does not exist in a row, the condition check is passed and the row meets the update conditions. If you set the passIfMissing parameter to false and the column does not exist in a row, the condition check fails and the row does not meet the update conditions. |
latestVersionOnly | Specifies whether to use only the latest version of value for comparison when a column has multiple versions of values. The value of this parameter is of the Boolean type. The default value is true, which specifies that if the column has multiple versions of values, only the latest version of value is used for comparison. If you set the latestVersionOnly parameter to false and the column has multiple versions of values, all versions of values are used for comparison. In this case, if at least one version meets the condition, the condition check is passed and the row meets the update conditions. |
Examples
Update a row based on the specified primary key. If the specified row exists, the value of the "name" column is "john", and the value of the "addr" column is "china", the update is successful. Otherwise, the update fails.
var params = {
tableName: "sampleTable",
primaryKey: [{ 'gid': Long.fromNumber(20013) }, { 'uid': Long.fromNumber(20013) }],
updateOfAttributeColumns: [{ 'PUT': [{ 'col1': 'test6' }] }]
};
// Specify the update conditions. Specify that data can be updated only if the following conditions are met: the specified row exists, the value of the "name" column is "john", and the value of the "addr" column is "china".
var condition = new TableStore.CompositeCondition(TableStore.LogicalOperator.AND);
condition.addSubCondition(new TableStore.SingleColumnCondition('name', 'john', TableStore.ComparatorType.EQUAL));
condition.addSubCondition(new TableStore.SingleColumnCondition('addr', 'china', TableStore.ComparatorType.EQUAL));
params.condition = new TableStore.Condition(TableStore.RowExistenceExpectation.EXPECT_EXIST, condition);
client.updateRow(params,
function (err, data) {
if (err) {
console.log('error:', err);
return;
}
console.log('success:', data);
});