Tüm Ürünler
Search

Bu Ürün

    Tablestore:Use local transactions

    Belge Merkezi

    Tablestore:Use local transactions

    Son Güncelleme:Oct 02, 2026

    Tablestore SDK for Java, belirtilen bir bölüm anahtarı değeri için yerel bir işlem çalıştırır. Böylece işlemdeki tüm yazma işlemleri ya tamamen uygulanır ya da tamamen iptal edilir. Yalıtım düzeyi Read Committed'tır.

    Ön koşullar

    • Tablestore SDK for Java bileşenini yükleyin ve istemciyi başlatın.

    • Tabloda yerel işlem özelliğini etkinleştirin. Bu özelliği tabloyu oluştururken aktif edebilirsiniz. Mevcut bir tabloda bu özelliği etkinleştirmek veya etkin olup olmadığını kontrol etmek için bir destek talebi gönderin .

    Açıklama

    Yerel bir işlem tek bir bölüm anahtarı değeriyle sınırlıdır. İşlem içindeki okuma ve yazma işlemleri bir işlem kimliği ile ilişkilendirilir ve taahhüt (commit) aşamasında atomik olarak geçerli hale gelir; yalıtım düzeyi Read Committed'tır. Yerel bir işlem aşağıdaki üç aşamadan oluşur:

    1. startLocalTransaction çağrısı işlemi başlatır ve işlem kimliğini döndürür.

    2. Sonraki her okuma veya yazma isteği, setTransactionId(txnId) yöntemiyle bu kimliği ekler.

    3. commitTransaction işlemi taahhüt eder; abortTransaction ise işlemi iptal eder.

    Bir işlem içinde desteklenen işlemler şunlardır: GetRow, PutRow, UpdateRow, DeleteRow, BatchWriteRow ve GetRange.

    public StartLocalTransactionResponse startLocalTransaction(StartLocalTransactionRequest request) throws TableStoreException, ClientException
public CommitTransactionResponse commitTransaction(CommitTransactionRequest request) throws TableStoreException, ClientException
public AbortTransactionResponse abortTransaction(AbortTransactionRequest request) throws TableStoreException, ClientException

public void setTransactionId(String transactionId)

    Aşağıdaki örnek, pkvalue bölüm anahtarı değeri üzerinde bir yerel işlem başlatır, birincil anahtarı (pkvalue, 10001) olan bir satır yazar ve işlemi taahhüt eder.

    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);

    Parametreler

    İşlemi başlatma isteği

    StartLocalTransactionRequest nesnesi aşağıdaki parametreleri içerir.


    Ad


    Tür


    Açıklama


    tableName (gerekli)


    String


    Veri tablosunun adı.


    primaryKey (gerekli)


    PrimaryKey


    İşlem kapsamını tanımlayan bölüm anahtarı değeri. Yerel bir işlem başlatırken yalnızca tablonun ilk birincil anahtar sütununu belirtin.


    rowKeys (isteğe bağlı)


    List<PrimaryKey>


    İşlem başladığında kilitlenecek satırların birincil anahtarları. Listeyi ayarlamak için setRowKeys() yöntemini veya listeye anahtar eklemek için addRowKey() yöntemini çağırın.

    İşlem içindeki istekler

    Bir işlem içinde kullanılan veri okuma ve yazma istekleri, aşağıdaki parametreyi içeren TxnRequest sınıfından türetilir.


    Ad


    Tür


    Açıklama


    transactionId (gerekli)


    String

    startLocalTransaction() tarafından döndürülen yerel işlem kimliği. İşlem içindeki her okuma veya yazma isteği, setTransactionId() çağrısıyla bu kimliği taşımak zorundadır.

    Taahhüt veya iptal isteği

    CommitTransactionRequest ve AbortTransactionRequest nesneleri aşağıdaki parametreyi içerir.


    Ad


    Tür


    Açıklama


    transactionID (gerekli)


    String


    Taahhüt edilecek veya iptal edilecek yerel işlem kimliği. İsteği oluştururken bu kimliği belirtin.

    Yanıt

    İşlem başlatma sonucu

    StartLocalTransactionResponse nesnesi aşağıdaki işleme özel alanı içerir.


    Ad


    Tür


    Açıklama


    transactionID


    String


    Yeni yerel işlemin kimliği. Değeri almak için getTransactionID() yöntemini çağırın ve bunu sonraki işlem bazlı veri operasyonlarında ve taahhüt veya iptal isteklerinde kullanın.

    Sınırlamalar

    • Yerel işlemler, otomatik artan birincil anahtar sütunlarıyla uyumlu değildir.

    • Yerel işlemler eşzamanlılık kontrolü için karamsar kilitleme (pessimistic locking) kullanır. Bir işlem sırasında bölüm anahtarı değeri üzerinde bir yazma kilidi tutulur; bu nedenle yalnızca işlem kimliğini taşıyan yazma istekleri başarılı olur.

    • Bir işlemin maksimum ömrü 60 saniyedir. Ardışık iki işlem arasında 60 saniyeden fazla süre geçerse işlem zaman aşımına uğrar ve sunucu işlemi iptal eder.

    • Aynı anda yalnızca bir istek bir işlem kimliğini kullanabilir. Aynı kimliği paylaşan eşzamanlı işlemlerin tümü başarısız olur.

    • Bir işlem içindeki her yazma isteği, işlemi başlatan aynı bölüm anahtarı değerini kullanmalıdır. Okuma isteklerinde böyle bir kısıtlama yoktur.

    • Tek bir işlem en fazla 4 MB veri yazabilir.

    • Bir işlem içindeki yazma işlemi bir sütun sürümü (zaman damgası) belirtmezse sunucu, zaman damgasını taahhüt anında değil yazma anında oluşturur. Kurallar normal bir yazma işlemiyle aynıdır.

    • Bir BatchWriteRow isteği bir işlem kimliği taşıyorsa, tüm satırlar işlemin başlatıldığı tabloyu hedeflemelidir.

    • İşlem herhangi bir yazma içermiyorsa taahhüt ve iptal aynı etkiye sahiptir.

    • Bir işlem kimliği taşıyan başarısız bir okuma veya yazma isteği işlemi sonlandırmaz. Yeniden deneme ilkesi uygulayabilir veya işlemi açıkça iptal edebilirsiniz.

    Örnekler

    İşlem içinde bir satır okuma

    Belirtilen bir bölüm anahtarı değeri için salt okunur bir işlem oluşturun ve bir satır okuyun.

    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);

    İşlem içinde birden çok satırı toplu yazma

    BatchWriteRowRequest.setTransactionId(txnId) çağrısı yaparak toplu yazma işlemine işlem kimliğini ekleyin. Her satırın bölüm anahtarı değeri, işlem başlatılırken kullanılan değerle eşleşmelidir; taahhüt aşamasında tüm satırlar atomik olarak uygulanır.

    String tableName = "local_tx_demo";

// 1. Start a local transaction. The partition key value of every row in the batch must match this 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. Build the batch write request and include the transaction ID.
BatchWriteRowRequest batchRequest = new BatchWriteRowRequest();
batchRequest.setTransactionId(txnId);

// Add multiple rows (pk1 of every row must equal the transaction's partition key value "pkvalue").
for (long pk2 = 20001; pk2 <= 20003; pk2++) {
    PrimaryKeyBuilder rowKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    rowKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString("pkvalue"));
    rowKeyBuilder.addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(pk2));
    RowPutChange rowPutChange = new RowPutChange(tableName, rowKeyBuilder.build());
    rowPutChange.addColumn(new Column("col1", ColumnValue.fromString("batch_" + pk2)));
    batchRequest.addRowChange(rowPutChange);
}

BatchWriteRowResponse batchResponse = client.batchWriteRow(batchRequest);
System.out.println("Batch all succeeded: " + batchResponse.isAllSucceed());

// 3. Commit the transaction so that all batch writes take effect atomically.
CommitTransactionRequest commitRequest = new CommitTransactionRequest(txnId);
client.commitTransaction(commitRequest);