Table Store Java SDK 寫入單行資料 - Tablestore

Java SDK 寫入單行資料的標準方式。支援條件寫入、自訂資料版本號碼和原子計數器，適用於訂單寫入、狀態更新和計數器等單行業務情境。

前提條件

安裝 Tablestore Java SDK並初始化用戶端。

功能說明

public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

寫入或更新單行資料。若行已存在，根據 condition 決定覆蓋、追加或拒絕。

以下樣本向資料表 put_row_demo 寫入主索引值為 row1 的一行資料，屬性列 col1 取值 val1。

String tableName = "put_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"));

PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Write CU: " + response.getConsumedCapacity().getCapacityUnit().getWriteCapacityUnit());

關鍵參數：

tableName（必選）：寫入的資料表名稱。
primaryKey（必選）：主鍵資訊，主鍵列名和值必須與資料表的主鍵結構一致。
columnsToPut（可選）：屬性列列表，通過 addColumn 添加。

參數說明

PutRowRequest 通過 RowPutChange 攜帶寫入參數，各參數說明如下。

名稱	類型	說明
tableName（必選）	String	寫入的資料表名稱。
primaryKey（必選）	PrimaryKey	主鍵資訊，包括主鍵列名稱和主索引值。主鍵列資料類型包括 STRING、INTEGER 和 BINARY。主鍵個數和類型必須與資料表的主鍵結構保持一致。主鍵列為自增列時，需將該列的值設定為預留位置，詳見自增主鍵列。
columnsToPut（可選）	List<Column>	屬性列列表，可通過多次調用 `addColumn` 逐列添加，或一次性傳入 `List<Column>` 構造。資料類型支援 STRING、INTEGER、BINARY、DOUBLE 和 BOOLEAN。資料版本號碼（時間戳記）預設由服務端自動產生，如需自訂，可在 `addColumn` 中傳入第三個參數 `timestamp`，詳見資料版本號碼。
condition（可選）	Condition	寫入條件，預設無條件覆蓋。詳見條件寫入。
returnType（可選）	ReturnType	傳回型別，通過 `setReturnType` 設定。 RT_NONE（預設）：不返回任何資料。 RT_PK：返回主鍵列，常用於自增列讀出。 RT_AFTER_MODIFY：返回修改後的列值，常用於原子計數器。

情境樣本

寫入多個屬性列

通過多次調用 addColumn 逐列添加，或一次性傳入 List<Column> 構造。

String tableName = "put_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row2"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);

// 方式一：多次調用 addColumn 逐列添加
rowPutChange.addColumn("name", ColumnValue.fromString("Alice"));
rowPutChange.addColumn("age", ColumnValue.fromLong(30));
rowPutChange.addColumn("active", ColumnValue.fromBoolean(true));

// 方式二：一次性傳入 List<Column> 構造
List<Column> columns = new ArrayList<>();
columns.add(new Column("score", ColumnValue.fromDouble(95.5)));
columns.add(new Column("city", ColumnValue.fromString("Hangzhou")));
rowPutChange.addColumns(columns);

client.putRow(new PutRowRequest(rowPutChange));

指定資料版本號碼

使用 addColumn(name, value, timestamp) 在寫入時指定資料版本號碼。

String tableName = "put_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row3"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);

long timestamp = System.currentTimeMillis();
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"), timestamp);

client.putRow(new PutRowRequest(rowPutChange));

自增列寫入返回主鍵

自增列的主索引值使用預留位置 PrimaryKeyValue.AUTO_INCREMENT，由服務端產生真實值。設定 setReturnType(ReturnType.RT_PK) 後，可通過 response.getRow() 讀出真實主鍵。

String tableName = "put_row_auto_inc_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("partition_key", PrimaryKeyValue.fromString("pk1"));
primaryKeyBuilder.addPrimaryKeyColumn("auto_id", PrimaryKeyValue.AUTO_INCREMENT);
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange(tableName, primaryKey);
rowPutChange.addColumn("payload", ColumnValue.fromString("hello"));
rowPutChange.setReturnType(ReturnType.RT_PK);

PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
Row returnedRow = response.getRow();
System.out.println("Returned PK: " + returnedRow.getPrimaryKey());

Tablestore：寫入單行資料