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

Java SDK 可向寬表模型資料表寫入或更新一行資料。

前提條件

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

功能說明

調用 putRow 向指定主鍵的行寫入屬性列。如果行已存在，將新增或覆蓋相應屬性列的資料版本；可通過 condition 控制寫入是否執行。

public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

以下樣本向資料表 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"));

client.putRow(new PutRowRequest(rowPutChange));

參數說明

PutRowRequest 包含以下參數。

名稱

類型

說明

rowChange（必選）

RowPutChange

單行寫入配置。

transactionId（可選）

String

局部事務 ID。僅在局部事務內寫入資料時設定。

關於如何擷取和使用該 ID，請參見局部事務。

行變更

rowChange 的類型為 RowPutChange，包含以下參數。

名稱	類型	說明
tableName（必選）	`String`	資料表名稱。
primaryKey（必選）	`PrimaryKey`	行主鍵。主鍵列的名稱、順序和類型必須與資料表的主鍵結構一致。主鍵列支援 `STRING`、`INTEGER` 和 `BINARY` 類型。自增主鍵列的值必須設定為 `PrimaryKeyValue.AUTO_INCREMENT`。
columnsToPut（可選）	`List<Column>`	要寫入的屬性列列表。可多次調用 `addColumn` 逐列添加，也可調用 `addColumns` 大量新增。
condition（可選）	`Condition`	寫入條件，預設不檢查行是否存在。關於條件的配置方法，請參見條件更新。
returnType（可選）	`ReturnType`	傳回型別。預設值為 `RT_NONE`，不返回主鍵資訊；設定為 `RT_PK` 時返回完整主鍵，常用於擷取自增主索引值。

屬性列

rowChange.columnsToPut[] 的類型為 Column，包含以下參數。

名稱	類型	說明
name（必選）	`String`	屬性列名稱。
value（必選）	`ColumnValue`	屬性列值。支援 `STRING`、`INTEGER`、`BINARY`、`DOUBLE` 和 `BOOLEAN` 類型。
timestamp（可選）	`long`	資料版本號碼，單位為毫秒。未設定時由服務端自動產生。

情境樣本

寫入多個屬性列

通過多次調用 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());