edit-icon download-icon

Conditional update

Last Updated: Mar 20, 2018

A conditional update is an update of table data that executes only when specified conditions are met. A conditional update can be based on a combination of up to 10 conditions. Supported conditions include arithmetic operations (=, !=, >, >=, <, and <=) and logical operations (NOT, AND, and OR). The conditional update is applicable to PutRow, UpdateRow, DeleteRow, and BatchWriteRow.

The column-based judgment conditions include the row existence condition and column-based condition.

  • The row existence condition is classified into IGNORE, EXPECT_EXIST, and EXPECT_NOT_EXIST. When a table needs to be updated, the system first checks the row existence condition. If the row existence condition is not met, an error occurs during the update.

  • The column-based condition supports SingleColumnValueCondition and CompositeColumnValueCondition, which are used to perform the condition-based judgment based on the values of a column or certain columns, similar to the conditions used by the Table Store filters.

Conditional update also supports optimistic locking strategy. That is, when a row needs to be updated, the system first obtains the value of a column. For example, the value of Column A is 1, and its condition is set as Column A = 1. Set Column A = 2, then update the row. If a failure occurs during the update, it means that the row has been successfully updated by another client.

Note: In highly concurrent applications such as webpage view counting or gaming (where atomic counter updates are required), the probability of failed conditional updates is high. If this occurs, we recommend that you retry the update until successful.


  1. Construct SingleColumnValueCondition.

    1. // set condition Col0==0.
    2. SingleColumnValueCondition singleColumnValueCondition = new SingleColumnValueCondition("Col0",
    3. SingleColumnValueCondition.CompareOperator.EQUAL, ColumnValue.fromLong(0));
    4. // If column Col0 does not exist, the condition check fails.
    5. singleColumnValueCondition.setPassIfMissing(false);
    6. // Only check the latest version
    7. singleColumnValueCondition.setLatestVersionsOnly(true);
  2. Construct CompositeColumnValueCondition.

    1. // condition composite1 is (Col0 == 0) AND (Col1 > 100)
    2. CompositeColumnValueCondition composite1 = new CompositeColumnValueCondition(CompositeColumnValueCondition.LogicOperator.AND);
    3. SingleColumnValueCondition single1 = new SingleColumnValueCondition("Col0",
    4. SingleColumnValueCondition.CompareOperator.EQUAL, ColumnValue.fromLong(0));
    5. SingleColumnValueCondition single2 = new SingleColumnValueCondition("Col1",
    6. SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100));
    7. composite1.addCondition(single1);
    8. composite1.addCondition(single2);
    9. // condition composite2 is ( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)
    10. CompositeColumnValueCondition composite2 = new CompositeColumnValueCondition(CompositeColumnValueCondition.LogicOperator.OR);
    11. SingleColumnValueCondition single3 = new SingleColumnValueCondition("Col2",
    12. SingleColumnValueCondition.CompareOperator.LESS_EQUAL, ColumnValue.fromLong(10));
    13. composite2.addCondition(composite1);
    14. composite2.addCondition(single3);
  3. Implement an increasing column by the optimistic locking strategy based on the conditional update.

    1. private static void updateRowWithCondition(SyncClient client, String pkValue) {
    2. // construct the primary
    3. PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    4. primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
    5. PrimaryKey primaryKey = primaryKeyBuilder.build();
    6. // read a row
    7. SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
    8. criteria.setMaxVersions(1);
    9. GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria));
    10. Row row = getRowResponse.getRow();
    11. long col0Value = row.getLatestColumn("Col0").getValue().asLong();
    12. // Col0 = Col0 + 1 by conditional update
    13. RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey);
    14. Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
    15. ColumnCondition columnCondition = new SingleColumnValueCondition("Col0", SingleColumnValueCondition.CompareOperator.EQUAL, ColumnValue.fromLong(col0Value));
    16. condition.setColumnCondition(columnCondition);
    17. rowUpdateChange.setCondition(condition);
    18. rowUpdateChange.put(new Column("Col0", ColumnValue.fromLong(col0Value + 1)));
    19. try {
    20. client.updateRow(new UpdateRowRequest(rowUpdateChange));
    21. } catch (TableStoreException ex) {
    22. System.out.println(ex.toString());
    23. }
    24. }


The following operations are examples of updates that are executed for highly concurrent applications:

  1. // Get the old value
  2. old_value = Read();
  3. // compute such as increment 1
  4. new_value = func(old_value);
  5. // Update by the new value
  6. Update(new_value);

The conditional update makes sure Update (new_value) if value equals to old_value in a highly concurrent environment where old_value may be updated by another client.


Writing or updating data successfully does not affect the capacity unit (CU) calculation rules of the interfaces. However, if the conditional update fails, one unit of write CU and one unit of read CU are consumed, which are billable.

Thank you! We've received your feedback.