Tablestore:Local transactions

Simple scenarios: Read and write data

Use the following two methods to perform read, modify, and write (RMW) operations. Each method has specific limits.

• Conditional update: processes only one request that involves a single row at a time. You cannot use this method to process requests that involve multiple data rows or requests that involve multiple write operations. For more information, see Conditional updates.

• Atomic counter: processes only one request that involves a single row at a time, and supports only the increment of column values. For more information, see Use the atomic counter feature.

To resolve the preceding issues, you can create a local transaction to perform RMW operations on data within the range specified by a partition key value.

1. Call the StartLocalTransaction operation to create a local transaction based on the specified partition key value and obtain the local transaction ID.

2. Call the GetRow or GetRange operation to read data. The request must contain the local transaction ID.

3. Modify data on the client.

4. Call the PutRow, UpdateRow, DeleteRow, or BatchWriteRow operation to write back the modified data. The request must contain the local transaction ID.

5. Call the CommitTransaction operation to commit the local transaction.

Complex scenario: mailbox scenario

Create a local transaction to perform atomic operations on the emails of a specific user.

To use the local transaction feature correctly, create two index tables on a data table. The following table lists the primary key columns for these tables. In the table, the Type column distinguishes the data table from the index tables. Each index row uses the IndexField column to store a field with a specific meaning, whereas the data table does not contain an IndexField column.

Specifically, you can use the local transaction feature to perform the following operations on emails.

Use the local transaction feature to write a data row

The following example creates a local transaction for a specified partition key value of a table and writes a row within the local transaction.

String tableName = "local_tx_demo";

// 1. Start a local transaction for the specified partition key value and obtain the transaction ID.
PrimaryKeyBuilder pkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
PrimaryKey partitionKey = pkBuilder.build();

StartLocalTransactionRequest startRequest =
        new StartLocalTransactionRequest(tableName, partitionKey);
String txnId = client.startLocalTransaction(startRequest).getTransactionID();

// 2. Write a row within the transaction. You must specify the full primary key and include the transaction ID.
PrimaryKeyBuilder rowKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
rowKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
rowKeyBuilder.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
PrimaryKey rowKey = rowKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, rowKey);
rowPutChange.addColumn(new Column("col1", ColumnValue.fromString("colvalue")));
rowPutChange.addColumn(new Column("col2", ColumnValue.fromLong(10)));

PutRowRequest putRequest = new PutRowRequest(rowPutChange);
putRequest.setTransactionId(txnId);
client.putRow(putRequest);

// 3. Commit the transaction to make all writes take effect. To discard changes, call abortTransaction() instead.
CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
client.commitTransaction(commitRequest);

Use the local transaction feature to read a data row

The following example creates a local transaction for a specified partition key value of a table and reads a row within the local transaction.

String tableName = "local_tx_demo";

// 1. Start a local transaction for the specified partition key value.
PrimaryKeyBuilder pkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
PrimaryKey partitionKey = pkBuilder.build();

StartLocalTransactionRequest startRequest =
        new StartLocalTransactionRequest(tableName, partitionKey);
String txnId = client.startLocalTransaction(startRequest).getTransactionID();

// 2. Read a row within the transaction. You must specify the full primary key and include the transaction ID.
PrimaryKeyBuilder rowKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
rowKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
rowKeyBuilder.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
PrimaryKey rowKey = rowKeyBuilder.build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, rowKey);
criteria.setMaxVersions(1);

GetRowRequest getRequest = new GetRowRequest(criteria);
getRequest.setTransactionId(txnId);
GetRowResponse getResponse = client.getRow(getRequest);

// 3. Commit or abort the transaction. For a read-only transaction, both have the same effect and release the transaction.
CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
client.commitTransaction(commitRequest);

Row row = getResponse.getRow();
System.out.println(row);