Tablestore:Local transactions

Simple scenarios: Read and write data

You can use the following two methods to perform read, modify, and write (RMW) operations. The two methods each 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 Atomic counters.

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 scenarios: Manage emails

You can create a local transaction to perform atomic operations on the emails of a specific user.

To use the local transaction feature, include two index tables in a data table. The following table describes the primary key columns of the data table and index tables. The Type column is used to identify the rows of the data table and those of the index tables. The IndexField column stores the $Folder field for the Folder index table, and the $SendTime field for the SendTime index table. The IndexField column is empty for the data table.

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 sample code shows how to create a local transaction based on the specified partition key value in a table and how to write a data row in the local transaction:

private static void transactionPutRow(SyncClient client) {
    // Specify the name of the data table. 
    String tableName="<TABLE_NAME>";
    // Create a local transaction based on the specified partition key value.  
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    // Specify the column name, data type, and column value of the partition key. 
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Construct a request to create a local transaction. 
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    // Initiate the request to create a local transaction and obtain the local transaction ID. 
    String txnId = client.startLocalTransaction(request).getTransactionID();
    
    // Write a data row in the local transaction. 
    // Configure the primary key information of the row. 
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    // Specify the column name, data type, and column value of the primary key. If the primary key of the table consists of multiple primary key columns, configure the information about the primary key columns in sequence. 
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    // Configure the attribute columns of the row. 
    RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey1);
    // Specify the column name, data type, and column value of each attribute column. Add more attribute columns as required. 
    rowPutChange.addColumn(new Column("col1", ColumnValue.fromString("colvalue")));
    rowPutChange.addColumn(new Column("col2", ColumnValue.fromLong(10)));
    PutRowRequest request1 = new PutRowRequest(rowPutChange);
    // Pass the local transaction ID to the request. 
    request1.setTransactionId(txnId);
    client.putRow(request1);
    
    // Commit or abort the local transaction.  
    // Commit the local transaction so that all data modifications in the local transaction take effect. 
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    // Abort the local transaction so that all data modifications in the local transaction do not take effect. 
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
}

Use the local transaction feature to read a data row

The following sample code shows how to create a local transaction based on the specified partition key value in a table and how to read a data row in the local transaction:

private static void transactionGetRow(SyncClient client) {
    // Specify the name of the data table. 
    String tableName="exampletabled";
    // Create a local transaction based on the specified partition key value. 
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    // Specify the column name, data type, and column value of the partition key. 
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Construct a request to create a local transaction. 
    StartLocalTransactionRequest request = new StartLocalTransactionRequest(tableName, primaryKey);
    // Initiate the request to create a local transaction and obtain the local transaction ID. 
    String txnId = client.startLocalTransaction(request).getTransactionID();

    // Read a data row in the local transaction. 
    // Configure the primary key information of the row. 
    PrimaryKeyBuilder primaryKeyBuilder1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    // Specify the column name, data type, and column value of the primary key. If the primary key of the table consists of multiple primary key columns, configure the information about the primary key columns in sequence. 
    primaryKeyBuilder1.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("111"));
    primaryKeyBuilder1.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(10001));
    PrimaryKey primaryKey1 = primaryKeyBuilder1.build();
    SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey1);
    // Read the latest version of data. 
    criteria.setMaxVersions(1);
    GetRowRequest request1 = new GetRowRequest(criteria);
    // Pass the local transaction ID to the request. 
    request1.setTransactionId(txnId);
    GetRowResponse getRowResponse = client.getRow(request1);
  
    // Commit or abort the local transaction. For a read operation, committing or aborting a local transaction has the same effect. 
    // Commit the local transaction so that all data modifications in the local transaction take effect. 
    CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
    client.commitTransaction(commitRequest);
    // Abort the local transaction so that all data modifications in the local transaction do not take effect. 
    //AbortTransactionRequest abortRequest = new AbortTransactionRequest(txnId);
    //client.abortTransaction(abortRequest);
    
    // Obtain and display the data row. 
    Row row = getRowResponse.getRow();
    System.out.println("The data row is read and displayed as follows:");
    System.out.println(row);
}