Atomic counters - Tablestore SDK for Java - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Description

Call increment(Column) to atomically update the specified integer column. A positive value increments and a negative value decrements. Tablestore guarantees row-level atomicity and writes a new data version after the update. To return the updated value in the same request, call addReturnColumn(String) and set returnType to RT_AFTER_MODIFY.

public UpdateRowResponse updateRow(UpdateRowRequest updateRowRequest) throws TableStoreException, ClientException
public RowUpdateChange increment(Column column)
public void addReturnColumn(String columnName)
public void setReturnType(ReturnType returnType)

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("Updated price: " + row.getLatestColumn("price").getValue().asLong());

Parameters

Request configuration

UpdateRowRequest contains the following parameters.

Name

Type

Description

rowChange (required)

RowUpdateChange

The single-row update configuration.

transactionId (optional)

String

The local transaction ID. Specify this parameter only when you perform the atomic counter operation in a local transaction.

For information about how to obtain and use the ID, see Use local transactions.

Row update configuration

The rowChange parameter of UpdateRowRequest is of the RowUpdateChange type.

Name	Type	Description
tableName (required)	String	The name of the data table.
primaryKey (required)	PrimaryKey	The primary key of the target row.
columnsToUpdate (required)	List<Pair<Column, Type>>	The attribute columns to update. Call `increment(Column)` to add an atomic counter operation.
condition (optional)	Condition	The conditional update configuration. The atomic counter operation is performed only when the row meets the condition. For information about how to configure the condition, see Use conditional updates.
returnType (optional)	ReturnType	The return type. Default value: `RT_NONE`. To return the updated value, set this parameter to `RT_AFTER_MODIFY`.
returnColumnNames (optional)	Set<String>	The atomic counter columns whose updated values are returned. Add column names by calling `addReturnColumn()` and use this parameter together with `RT_AFTER_MODIFY`.

Counter column

Each element added to UpdateRowRequest.rowChange.columnsToUpdate by increment() contains a Column.

Name	Type	Description
name (required)	String	The name of the attribute column on which to perform the atomic counter operation.
value (required)	ColumnValue	The integer increment. A positive value increments and a negative value decrements. The result must not overflow. If the target column does not exist, its initial value is treated as 0.

Response

Name	Type	Description
row	Row	If `RT_AFTER_MODIFY` is specified, this field contains the updated values of the atomic counter columns added by `addReturnColumn()`. Call `getRow()` to obtain the value.

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.
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.