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

Prerequisites

Install Tablestore SDK for Java and initialize the client.

Description

public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

Writes or updates a single row. If the row exists, the condition parameter determines whether to overwrite, append, or reject the write.

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

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

Key parameters:

tableName (required): The name of the table to write to.
primaryKey (required): The primary key. Column names and values must match the primary key schema of the table.
columnsToPut (optional): The list of attribute columns. Add columns by calling addColumn.

Parameters

PutRowRequest wraps a RowPutChange that holds the write parameters:

Name	Type	Description
tableName (required)	String	The name of the table to write to.
primaryKey (required)	PrimaryKey	The primary key, including column names and values. Supported data types are STRING, INTEGER, and BINARY. The number and types of primary key columns must match the table's primary key schema. For an auto-increment primary key column, set the column value to the placeholder. For more information, see Auto-increment primary key column.
columnsToPut (optional)	List<Column>	The list of attribute columns. Add columns one at a time by calling `addColumn` multiple times, or pass a `List<Column>` in a single call. Supported data types are STRING, INTEGER, BINARY, DOUBLE, and BOOLEAN. The data version (timestamp) is generated by the server by default. To set a custom version, pass `timestamp` as the third argument to `addColumn`. For more information, see Data version.
condition (optional)	Condition	The write condition. By default, the write overwrites any existing row. For more information, see Conditional write.
returnType (optional)	ReturnType	The return type, set with `setReturnType`. RT_NONE (default): No data is returned. RT_PK: Returns the primary key columns. Typically used to retrieve auto-increment column values. RT_AFTER_MODIFY: Returns the modified column values. Typically used with atomic counters.

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

References

Batch write rows