Use atomic counters

Prerequisites

Install the Tablestore SDK for Go and initialize the client.

Description

Call IncrementColumn to perform an atomic counter operation on an INTEGER attribute column. A positive value increments the column, and a negative value decrements it. The server guarantees row-level atomicity and writes a new data version. To return the updated value in the same request, call AppendIncrementColumnToReturn to specify the column and call SetReturnIncrementValue to set the return type.

func (rowchange *UpdateRowChange) IncrementColumn(columnName string, value int64)
func (rowchange *UpdateRowChange) AppendIncrementColumnToReturn(name string)
func (rowchange *UpdateRowChange) SetReturnIncrementValue()

The following sample increments the score column of row1 in the example_table table by 10 and returns the updated value.

primaryKey := &tablestore.PrimaryKey{}
primaryKey.AddPrimaryKeyColumn("id", "row1")

change := &tablestore.UpdateRowChange{
    TableName:  "example_table",
    PrimaryKey: primaryKey,
}
change.IncrementColumn("score", int64(10))
change.SetCondition(tablestore.RowExistenceExpectation_EXPECT_EXIST)
change.AppendIncrementColumnToReturn("score")
change.SetReturnIncrementValue()

response, err := client.UpdateRow(&tablestore.UpdateRowRequest{UpdateRowChange: change})
if err != nil {
    log.Fatal(err)
}
fmt.Println(response.Columns[0].Value)

Parameters

UpdateRowChange contains the following parameters related to atomic counters.

Name	Type	Description
TableName (required)	`string`	The table name.
PrimaryKey (required)	`*PrimaryKey`	The complete primary key of the target row.
Columns (required)	`[]ColumnToUpdate`	The attribute column operations. Call `IncrementColumn` to add an atomic counter operation. A positive increment increases the INTEGER column, and a negative increment decreases it. If the column does not exist, the initial value is `0`.
Condition (required)	`*RowCondition`	The update condition. For more information, see Use conditional updates.
ReturnType (optional)	`ReturnType`	The return type. Calling `SetReturnIncrementValue` sets this parameter to `ReturnType_RT_AFTER_MODIFY`.
ColumnNamesToReturn (optional)	`[]string`	The atomic counter columns whose updated values are returned. Call `AppendIncrementColumnToReturn` to add a column.
TransactionId (optional)	`*string`	The local transaction ID. Specify this parameter only for an atomic counter operation in a local transaction.

Response

UpdateRowResponse contains the following business field related to atomic counters.

Field	Type	Description
`Columns`	`[]*AttributeColumn`	When `ReturnType_RT_AFTER_MODIFY` is specified, this field contains the updated values of the columns specified by `AppendIncrementColumnToReturn`.

Limits

Only INTEGER attribute columns are supported. If the target column does not exist, the initial value is 0. If the column exists but is not an INTEGER column, a parameter error is returned.
The increment can be positive or negative, but the result must not overflow.
An atomic counter operates only on the latest version and does not support a specified timestamp. The operation writes a new version.
In the same request, an atomic counter operation and another operation, such as an overwrite or deletion, cannot be performed on the same column.
In a BatchWriteRow request, a row that contains an atomic counter operation can appear only once.

Important

A network timeout or system error may cause the client to retry and execute an atomic counter operation more than once. If you must precisely control the final column value, use conditional updates to implement optimistic locking.