Atomically increment or decrement a column

Online counting workloads often require concurrent increments or decrements on the same integer column and immediate read-back of the updated value. The Tablestore SDK for Java exposes row-level atomic increment and decrement on RowUpdateChange, completing the update and optionally returning the new value in a single request.

Prerequisites

Tablestore SDK for Java installed
Initialized client

public RowUpdateChange increment(Column column)
public void addReturnColumn(String columnName)
public void setReturnType(ReturnType returnType)

Use RowUpdateChange.increment(Column) to atomically increment or decrement the specified integer column at the row level. The operation is atomic. Tablestore writes a new data version after each update.

The following example increments the price column by 10 for the row with primary key pk0 in the counter_demo table and reads the updated value in the same request.

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("pk0"))
        .build();

RowUpdateChange rowUpdateChange = new RowUpdateChange("counter_demo", primaryKey);

// Increment the price column by 10 (use a negative value to decrement)
rowUpdateChange.increment(new Column("price", ColumnValue.fromLong(10)));

// Return the updated column value in the same request
rowUpdateChange.addReturnColumn("price");
rowUpdateChange.setReturnType(ReturnType.RT_AFTER_MODIFY);

UpdateRowResponse response = client.updateRow(new UpdateRowRequest(rowUpdateChange));
Row row = response.getRow();
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Updated price: " + row.getLatestColumn("price").getValue().asLong());

Key methods:

increment(Column): Atomically increments or decrements the specified integer column. A positive value increments and a negative value decrements.
addReturnColumn(String): Specifies the column whose updated value is returned in the response.
setReturnType(ReturnType): Sets the response return type. Set this to ReturnType.RT_AFTER_MODIFY to return the updated value of the atomic counter column.

Parameters

Name	Type	Description
tableName (Required)	String	The name of the data table.
columnName (Required)	String	The name of the column on which to perform the atomic counter operation. Only integer columns are supported. If the column does not exist, Tablestore creates it and initializes the value with the increment.
value (Required)	long	The increment or decrement value applied to the column. A positive value increments and a negative value decrements. If the result overflows, the operation returns the `OTSParameterInvalid` error.
returnType (Optional)	ReturnType	Specifies whether the response includes the updated column value. By default, the updated column value is not returned. Set this parameter to `ReturnType.RT_AFTER_MODIFY` and call `addReturnColumn` to receive the updated column value in the response.

Limitations

Atomic counter operations support only integer columns. If the column exists but is not an integer column, the operation returns the OTSParameterInvalid error.
Atomic counter operations apply only to the latest version and do not accept a user-specified timestamp. Each update writes a new data version.
Within a single update request, you cannot combine an atomic counter operation with other operations on the same column, such as overwrite or delete.
In a BatchWriteRow request, a row with an atomic counter operation can appear only once.

Important

Atomic counter operations may fail because of network timeouts or system errors. A retry can apply the increment twice, leaving the counter higher (or lower) than intended by the increment value. To avoid double counting, use conditional update to update the value based on its current state.