All Products
Search
Document Center

Tablestore:Use the atomic counter feature

Last Updated:Sep 09, 2024

If you want to use a counter for your online application, you can use the atomic counter feature. To use this feature, specify a column as an atomic counter and perform atomic counter operations on the column.

Prerequisites

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.

API operations

The API operations that you can call to use the atomic counter feature are added to the rowUpdateChange class. The following table describes the operations.

Operation

Description

RowUpdateChange Increment(Column column)

Increases or decreases the value in a column by a number.

List<String> ReturnColumnNames

Specifies the name of the column whose value you want to return among the columns on which operations are performed to implement atomic counter.

ReturnType ReturnType

Specifies a data type to return the value of an atomic counter.

Parameters

Parameter

Description

TableName

The name of the data table.

ColumnName

The name of the column on which you want to perform atomic counter operations. You can specify a column only of the INTEGER type.

Value

The increment or decrement in the column value.

ReturnColumnNames

Specifies the name of the column whose value you want to return among the columns on which operations are performed to implement atomic counter.

ReturnType

If you set this parameter to ReturnType.RT_AFTER_MODIFY, the value of the atomic counter is returned.

Example

The following sample code shows how to call the rowUpdateChange operation to increase the value of a column of the INTEGER type when data is written and how to read the new values of the column.

public static void Increment(int incrementValue)
{
    Console.WriteLine("Start set increment column...");
    OTSClient otsClient = Config.GetClient();

    // Specify the primary key of the row. The primary key must be consistent with the primary key specified in TableMeta when you create the table. 
    PrimaryKey primaryKey = new PrimaryKey
    {
        { Pk1, new ColumnValue(0) },
        { Pk2, new ColumnValue("abc") }
    };
    RowUpdateChange rowUpdateChange = new RowUpdateChange(TableName, primaryKey); // Specify the name of the data table. 
    // Set the ReturnType parameter to ReturnType.RT_AFTER_MODIFY to return the values of the column on which atomic counter operations are performed. 
    rowUpdateChange.ReturnType = ReturnType.RT_AFTER_MODIFY;
    rowUpdateChange.ReturnColumnNames = new List<string>() { IncrementCol};
    // Specify the column on which atomic counter operations are performed. The column value starts from 0 and increases by the number specified by the incrementValue parameter. 
    rowUpdateChange.Increment(new Column(IncrementCol, new ColumnValue(incrementValue)));

    UpdateRowRequest updateRowRequest = new UpdateRowRequest(rowUpdateChange);

    var response = otsClient.UpdateRow(updateRowRequest);
    Console.WriteLine("set Increment column succeed Increment result:" + response.Row.GetColumns()[0].Value);
}