Tablestore:Use the atomic counter feature

Scenarios

Atomic counters are suitable for scenarios in which you need to quickly perform counting operations, such as counting the number of real-time page views (PVs) on various topics and the number of messages in some online applications.

Overview

Atomic counters reduce the write performance overhead caused by strong consistency. When you send a request to a server to perform read, modify, and write (RMW) operations, the server performs the operations on a row by locking the row. To ensure strong data consistency, you can update atomic counters on a database server to improve write performance.

You can use the atomic counter feature to collect real-time statistics on the data in a row. To implement the atomic counter feature, you can call the UpdateRow operation to perform operations on atomic counters, such as incrementing or decrementing an atomic counter value and returning an updated atomic counter value.

For example, you create a Tablestore table to store metadata of pictures and count the number of pictures. Each row in the table has a user ID. A column of the row is used to store metadata of pictures. Another column of the row is used as an atomic counter to count the real-time number of pictures whose metadata is stored in the row.

• When you call the UpdateRow operation to add the metadata of a picture to a row, the atomic counter value is increased by 1.

• When you call the UpdateRow operation to delete the metadata of a picture from a row, the atomic counter value is decreased by 1.

• You can call the GetRow operation to read the value of the atomic counter to obtain the number of pictures whose metadata is stored in the row.

This ensures strong database consistency. When you add the metadata of a picture to a row, the atomic counter value of the row is increased by 1 instead of decreased by 1.

Usage notes

• You can implement atomic counters only on INTEGER columns.

• If a column that is specified as an atomic counter does not exist before you write data, the default value of the column is 0. If a column that is specified as an atomic counter is not an INTEGER column, an OTSParameterInvalid error occurs.

• You can update an atomic counter by using a positive or negative number, but you must avoid an integer overflow. If an integer overflow occurs, an OTSParameterInvalid error is returned.

• By default, the value of an atomic counter is not returned in the response to an update row request. You can specify that the updated value of an atomic counter is returned.

• You cannot specify a column as an atomic counter and update the column in a single update request. For example, if you set Column A to an atomic counter, you cannot perform other operations such as overwrite and delete operations on the column at the same time.

• You can perform multiple update operations on the same row by sending a BatchWriteRow request. However, if you perform an atomic counter operation on a row, you can perform only one update operation on the row in a BatchWriteRow request.

• Only the value of the latest version of an atomic counter can be updated. You cannot update the value of a specified version of an atomic counter. After an update operation is complete, a new version of data is inserted into the atomic counter in the row.

Methods

You can use the atomic counter feature by using Tablestore SDK for Java, Tablestore SDK for Go, Tablestore SDK for Python, Tablestore SDK for Node.js, Tablestore SDK for .NET, and Tablestore SDK for PHP. In this example, Tablestore SDK for Java is used.

The following code provides an example on how to use rowUpdateChange to increase the value of an atomic counter and return the increased value:

private static void incrementByUpdateRowApi(SyncClient client) {
        // Specify the primary key.
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString("pk0"));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        // Specify the table.
        RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey); 

        // Set the price column as an atomic counter and increase the value of the atomic counter by 10. You cannot specify the timestamp.
        rowUpdateChange.increment(new Column("price", ColumnValue.fromLong(10)));

        // Set the data type of the value to return to ReturnType.RT_AFTER_MODIFY and return the value of the atomic counter.
        rowUpdateChange.addReturnColumn("price");
        rowUpdateChange.setReturnType(ReturnType.RT_AFTER_MODIFY);

        // Initiate a request to update the row.
        UpdateRowResponse response = client.updateRow(new UpdateRowRequest(rowUpdateChange));

        // Display the updated values.
        Row row = response.getRow();
        System.out.println(row);
    }

Billing

The implementation of atomic counters does not affect the existing billing rules. For more information about billing, see Billing overview.