Tüm Ürünler
Search
Belge Merkezi

Tablestore:Write data

Son Güncelleme:Oct 02, 2026

Tablestore, tablolara veri yazmak için üç işlem sunar: PutRow, UpdateRow ve BatchWriteRow.

Not

Satırlar, tabloların temel birimleridir. Her satır birincil anahtar sütunlarından ve isteğe bağlı öznitelik sütunlarından oluşur. Bir tablodaki tüm satırlarda birincil anahtar sütunu adları ve türleri aynıdır. Öznitelik sütunları satırlar arasında farklılık gösterebilir. Daha fazla bilgi için bkz. Genel bakış.

İşlemler

İşlem Kapsam Davranış
PutRow Tek satır Bir satır ekler. Aynı birincil anahtara sahip bir satır varsa, tüm sütunlardaki verinin tüm sürümlerini siler ve yeni veriyi yazar.
UpdateRow Tek satır Öznitelik sütunlarını ekler, günceller veya kaldırır. Bir sütundan belirli bir veri sürümünü siler. Satır yoksa yeni bir satır ekler (istek yalnızca sütun kaldırmayı içermiyorsa).
BatchWriteRow Birden çok satır Tek bir istekte, bir veya daha fazla tablo üzerinde birden çok PutRow, UpdateRow ve DeleteRow alt işlemini birleştirir. Her alt işlem bağımsız olarak yürütülür ve yanıtlanır.

Ortak ayarlar

Veri yazmadan önce, herhangi bir yazma işlemi için aşağıdaki isteğe bağlı ayarları yapılandırabilirsiniz:

  • Veri sürüm numarası: Tablestore varsayılan olarak geçerli UNIX zaman damgasını (January 1, 1970, 00:00:00 UTC'den itibaren geçen milisaniye) sürüm numarası olarak kullanır. Gerekirse özel bir sürüm numarası belirtin. Daha fazla bilgi için bkz. Veri sürümleri ve TTL.

  • Koşullu güncelleme: Bir satır varlığı koşulu veya sütun değerlerine dayalı bir koşul ayarlayın. Daha fazla bilgi için bkz. Koşullu güncellemeler.

PutRow yanıtı

  • Başarı durumunda Tablestore tüketilen kapasite birimi (CU) sayısını döndürür.

  • Hata durumunda Tablestore bir hata kodu döndürür (örneğin, parametre doğrulama hatası, aşırı satır verisi veya satır varlığı kontrolü hatası).

Not

Hata kodları hakkında daha fazla bilgi için bkz. Hata kodları.

BatchWriteRow kısmi hata yönetimi

Bir BatchWriteRow isteğinde bazı satırlar başarısız olduğunda Tablestore özel durum oluşturmaz. Bunun yerine, başarısız satırlarla ilgili bilgileri içeren bir BatchWriteRowResponse döndürür. Tüm satırların başarıyla yazılıp yazılmadığını kontrol etmek için her zaman isAllSucceed yöntemini çağırın.

Sunucu bazı işlemlerde geçersiz parametreler algılarsa, istekteki herhangi bir işlemi gerçekleştirmeden önce hata döndürebilir.

BatchWriteRow ayrıca işlem başına koşulları da destekler; her PutRow, UpdateRow veya DeleteRow alt işlemi için güncelleme koşullarını ayrı ayrı yapılandırın.

Tablestore konsolunu kullanın

Tablestore konsolu tek bir satır veri eklemeyi ve güncellemeyi destekler.

  1. Tablestore konsoluna giriş yapın.

  2. Overview sayfasında hedef örneği bulun ve Actions sütununda Manage Instance öğesini tıklayın.

  3. Instance Details sekmesinin Tables sekmesinde hedef tablonun adını tıklayın.

  4. Tabloyu Yönet sayfasının Query Data sekmesinde veriyi ekleyin veya güncelleyin.

Tek satır ekleme

  1. Insert öğesini tıklayın.

  2. Insert iletişim kutusunda Birincil Anahtar Değeri sütununa değerleri girin.

  3. image simgesini tıklayın ve Ad, Tür, Değer ve Sürüm parametrelerini yapılandırın. Birden çok öznitelik sütunu eklemek için her seferinde bir sütun eklemek ve parametrelerini yapılandırmak üzere image simgesini tıklayın.

  4. OK öğesini tıklayın.

Tek satır güncelleme

  1. Güncellenecek satırı seçin ve Update öğesini tıklayın.

  2. Update iletişim kutusunda öznitelik sütunlarını değiştirin:

    • Sütun ekleme: image simgesini tıklayın ve parametreleri yapılandırın.

    • Sütun kaldırma: Actions açılır listesinden Delete All öğesini seçin.

    • Belirli bir sürümü silme: Actions açılır listesinden Delete öğesini seçin ve silinecek sürüm numarasını seçin.

    • Değer güncelleme: Actions açılır listesinden Update öğesini seçin ve değeri değiştirin.

  3. OK öğesini tıklayın.

Tablestore CLI'yi kullanın

Satır ekleme

put komutunu çalıştırın. Daha fazla bilgi için bkz. Veri ekleme.

Aşağıdaki örnekte ilk birincil anahtar sütunu 86 ve ikinci birincil anahtar sütunu 6771 olan bir satır eklenir. Satırın name ve country olmak üzere iki STRING öznitelik sütunu vardır.

put --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'

Satır güncelleme

update komutunu çalıştırın. Daha fazla bilgi için bkz. Veri güncelleme.

Aşağıdaki örnekte ilk birincil anahtar sütunu 86 ve ikinci birincil anahtar sütunu 6771 olan satır güncellenir. --condition ignore bayrağı, satırın var olup olmadığından bağımsız olarak veriyi ekler. Satır varsa yeni veri mevcut verinin üzerine yazar.

update --pk '["86", 6771]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]' --condition ignore

Tablestore SDK'larını kullanın

Aşağıdaki SDK'lardan birini kullanarak veri yazın: Tablestore SDK for Java, Tablestore SDK for Go, Tablestore SDK for Python, Tablestore SDK for Node.js, Tablestore SDK for .NET veya Tablestore SDK for PHP.

Aşağıdaki örnekler Java SDK'sını kullanır.

Tek satır ekleme

PutRow, sistem tarafından oluşturulan sürüm numaralarını, özel sürüm numaralarını ve koşullu yazmaları destekler.

Sistem tarafından oluşturulan sürüm numarası

Her biri bir veri sürümü depolayan 10 öznitelik sütunu içeren bir satır ekleyin. Sistem sürüm numaralarını otomatik olarak oluşturur.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Add attribute columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Özel sürüm numarası

Her biri özel sürüm numaralarına sahip üç veri sürümü depolayan 10 öznitelik sütunu içeren bir satır ekleyin.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Satır varlığı koşulu

Belirtilen satır olmadığında, her biri üç sürüm içeren 10 öznitelik sütunu olan bir satır ekleyin.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition that expects the specified row to not exist.
    rowPutChange.setCondition(new Condition(RowExistenceExpectation.EXPECT_NOT_EXIST));

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Satır varlığı ve sütun değeri koşulları

Satır mevcut olduğunda ve Col0 değeri 100'den büyük olduğunda, her biri üç sürüm içeren 10 öznitelik sütunu olan bir satır ekleyin.

private static void putRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowPutChange rowPutChange = new RowPutChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition and a column-based condition that expect the specified row to exist and the value of the Col0 column to be greater than 100.
    Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
    condition.setColumnCondition(new SingleColumnValueCondition("Col0",
            SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
    rowPutChange.setCondition(condition);

    // Add attribute columns.
    long ts = System.currentTimeMillis();
    for (int i = 0; i < 10; i++) {
        for (int j = 0; j < 3; j++) {
            rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j));
        }
    }

    client.putRow(new PutRowRequest(rowPutChange));
}

Tek satır güncelleme

UpdateRow, koşulsuz güncellemeleri ve satır varlığı ile sütun değerlerine dayalı koşullu güncellemeleri destekler.

Koşulsuz güncelleme

Birden çok sütunu güncelleyin, bir sütundan belirli bir veri sürümünü silin ve bir sütunu kaldırın.

private static void updateRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", primaryKey);

    // Update columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    // Delete a specific version of data from a column.
    rowUpdateChange.deleteColumn("Col10", 1465373223000L);

    // Remove a column.
    rowUpdateChange.deleteColumns("Col11");

    client.updateRow(new UpdateRowRequest(rowUpdateChange));
}

Satır varlığı ve sütun değeri koşulları

Satır mevcut olduğunda ve Col0 değeri 100'den büyük olduğunda bir satırı güncelleyin.

private static void updateRow(SyncClient client, String pkValue) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue));
    PrimaryKey primaryKey = primaryKeyBuilder.build();
    // Specify the name of the table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", primaryKey);

    // Specify a row existence condition and a column-based condition that expect the specified row to exist and the value of the Col0 column to be greater than 100.
    Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST);
    condition.setColumnCondition(new SingleColumnValueCondition("Col0",
            SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)));
    rowUpdateChange.setCondition(condition);

    // Update columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }

    // Delete a specific version of data from a column.
    rowUpdateChange.deleteColumn("Col10", 1465373223000L);

    // Remove a column.
    rowUpdateChange.deleteColumns("Col11");

    client.updateRow(new UpdateRowRequest(rowUpdateChange));
}

Birden çok satırı aynı anda yazma

Aşağıdaki örnekte iki PutRow işlemi, bir UpdateRow işlemi ve bir DeleteRow işlemi içeren bir BatchWriteRow isteği gönderilir.

private static void batchWriteRow(SyncClient client) {
    BatchWriteRowRequest batchWriteRowRequest = new BatchWriteRowRequest();

    // Construct rowPutChange1.
    PrimaryKeyBuilder pk1Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk1Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk1"));
    // Specify the name of the data table.
    RowPutChange rowPutChange1 = new RowPutChange("<TABLE_NAME>", pk1Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange1.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Add rowPutChange1 to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowPutChange1);

    // Construct rowPutChange2.
    PrimaryKeyBuilder pk2Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk2Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk2"));
    // Specify the name of the data table.
    RowPutChange rowPutChange2 = new RowPutChange("<TABLE_NAME>", pk2Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowPutChange2.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Add rowPutChange2 to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowPutChange2);

    // Construct rowUpdateChange.
    PrimaryKeyBuilder pk3Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk3Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk3"));
    // Specify the name of the data table.
    RowUpdateChange rowUpdateChange = new RowUpdateChange("<TABLE_NAME>", pk3Builder.build());
    // Add columns.
    for (int i = 0; i < 10; i++) {
        rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
    }
    // Remove a column.
    rowUpdateChange.deleteColumns("Col10");
    // Add rowUpdateChange to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowUpdateChange);

    // Construct rowDeleteChange.
    PrimaryKeyBuilder pk4Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    pk4Builder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk4"));
    // Specify the name of the data table.
    RowDeleteChange rowDeleteChange = new RowDeleteChange("<TABLE_NAME>", pk4Builder.build());
    // Add rowDeleteChange to the code of the batch operation.
    batchWriteRowRequest.addRowChange(rowDeleteChange);

    BatchWriteRowResponse response = client.batchWriteRow(batchWriteRowRequest);

    System.out.println("Whether all operations are successful:" + response.isAllSucceed());
    if (!response.isAllSucceed()) {
        for (BatchWriteRowResponse.RowResult rowResult : response.getFailedRows()) {
            System.out.println("Failed rows:" + batchWriteRowRequest.getRowChange(rowResult.getTableName(), rowResult.getIndex()).getPrimaryKey());
            System.out.println("Cause of failures:" + rowResult.getError());
        }
        /**
         * You can use the createRequestForRetry method to construct another request to retry the operations on failed rows. Only the retry request is constructed here.
         * We recommend that you use the custom retry policy in Tablestore SDKs as the retry method. This feature allows you to retry failed rows after batch operations. After you set the retry policy, you do not need to add retry code to call the operation.
         */
        BatchWriteRowRequest retryRequest = batchWriteRowRequest.createRequestForRetry(response.getFailedRows());
    }
}

Faturalama

Yazma işlemleri tüketilen CU sayısına göre ücretlendirilir. Ölçülen okuma ve yazma CU'ları ile rezerve okuma ve yazma CU'ları ayrı ayrı ücretlendirilir. Örnek türü hangi CU türünün tüketileceğini belirler.

Not

Örnek türleri ve CU'lar hakkında daha fazla bilgi için bkz. Örnekler ve Okuma ve yazma aktarım hızı.

Yazma CU hesaplaması

İşlem Formül
PutRow Yukarı yuvarlanmış: (Tüm birincil anahtar sütunlarının boyutu + Eklenen öznitelik sütunlarının boyutu) / 4 KB
UpdateRow Yukarı yuvarlanmış: (Tüm birincil anahtar sütunlarının boyutu + Güncellenen öznitelik sütunlarının boyutu) / 4 KB. Sütun kaldırma işlemleri için sütun adı uzunluğu sütun boyutu olarak sayılır.
DeleteRow (BatchWriteRow içinde) Yukarı yuvarlanmış: Tüm birincil anahtar sütunlarının boyutu / 4 KB

Okuma CU hesaplaması

Okuma CU'ları yalnızca condition parametresi IGNORE olarak ayarlanmadığında tüketilir.

İşlem Formül Koşul karşılanmadığında
PutRow Yukarı yuvarlanmış: Tüm birincil anahtar sütunlarının boyutu / 4 KB İşlem başarısız olur. 1 yazma CU ve 1 okuma CU tüketir.
UpdateRow Yukarı yuvarlanmış: Tüm birincil anahtar sütunlarının boyutu / 4 KB İşlem başarısız olur. 1 yazma CU ve 1 okuma CU tüketir.
DeleteRow (BatchWriteRow içinde) Yukarı yuvarlanmış: Tüm birincil anahtar sütunlarının boyutu / 4 KB İşlem başarısız olur. 1 yazma CU ve 1 okuma CU tüketir.