Write a row - Tablestore SDK for Java - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

Install Tablestore SDK for Java and initialize the client.

Description

Call putRow to write attribute columns to a row identified by its primary key. If the row exists, Tablestore adds or overwrites the corresponding attribute column versions. You can use condition to control whether the write is performed.

public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

The following example writes a row to the put_row_demo table with primary key column id set to row1 and attribute column col1 set to 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));

Parameters

PutRowRequest contains the following parameters.

Name	Type	Description
rowChange (required)	`RowPutChange`	The configurations for writing a row.
transactionId (optional)	`String`	The local transaction ID. Set this parameter only when you write data in a local transaction.

Row change

rowChange is of the RowPutChange type and contains the following parameters.

Name	Type	Description
tableName (required)	`String`	The name of the table.
primaryKey (required)	`PrimaryKey`	The primary key of the row. The names, order, and types of the primary key columns must match the table schema. Primary key columns support the `STRING`, `INTEGER`, and `BINARY` types. Set an auto-increment primary key column to `PrimaryKeyValue.AUTO_INCREMENT`.
columnsToPut (optional)	`List<Column>`	The attribute columns to write. Call `addColumn` multiple times to add columns one by one, or call `addColumns` to add multiple columns.
condition (optional)	`Condition`	The write condition. By default, Tablestore does not check whether the row exists.
returnType (optional)	`ReturnType`	The return type. The default value is `RT_NONE`, which does not return primary key information. Set this parameter to `RT_PK` to return the complete primary key, typically to retrieve an auto-increment primary key value.

Attribute columns

Each element in rowChange.columnsToPut[] is of the Column type and contains the following parameters.

Name	Type	Description
name (required)	`String`	The name of the attribute column.
value (required)	`ColumnValue`	The value of the attribute column. Supported types are `STRING`, `INTEGER`, `BINARY`, `DOUBLE`, and `BOOLEAN`.
timestamp (optional)	`long`	The data version number. Unit: milliseconds. If you do not specify this parameter, the server generates the value.

Examples

Write multiple attribute columns

The example shows both approaches — calling addColumn per column, and passing a prepared List<Column> in one call.

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

// Option 1: Add columns one at a time with addColumn
rowPutChange.addColumn("name", ColumnValue.fromString("Alice"));
rowPutChange.addColumn("age", ColumnValue.fromLong(30));
rowPutChange.addColumn("active", ColumnValue.fromBoolean(true));

// Option 2: Pass a List<Column> in a single call
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));

Specify the data version

Use addColumn(name, value, timestamp) to set a custom data version when you write the column.

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

Return the primary key for an auto-increment column

For an auto-increment primary key column, set the column value to the placeholder PrimaryKeyValue.AUTO_INCREMENT — the server generates the actual value at write time. To retrieve the generated value in the response, call setReturnType(ReturnType.RT_PK) before writing, then call response.getRow() after the write returns.

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