All Products
Search

This Product

    Tablestore:Update a row

    Document Center

    Tablestore:Update a row

    Last Updated:Jun 25, 2026

    Locate a row by primary key and incrementally add, modify, or delete its attribute columns, optionally with a specified version number. The Java SDK uses UpdateRow for atomic single-row updates. Common use cases include refreshing status fields, archiving historical values, and logical deletion.

    Prerequisites

    The Tablestore SDK for Java is installed and an OTSClient instance is initialized.

    Description

    public UpdateRowResponse updateRow(UpdateRowRequest updateRowRequest) throws TableStoreException, ClientException

    Locate a single row by primary key and incrementally update its attribute columns. Use RowUpdateChange to hold the primary key and the column change operations. Get the consumed capacity unit (CU) from response.getConsumedCapacity().

    The following example updates row row1 in the update_row_demo data table, setting attribute column col1 to changed_val1.

    String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
rowUpdateChange.put("col1", ColumnValue.fromString("changed_val1"));

UpdateRowResponse response = client.updateRow(new UpdateRowRequest(rowUpdateChange));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Write CU: " + response.getConsumedCapacity().getCapacityUnit().getWriteCapacityUnit());

    Parameters

    The RowUpdateChange object carries the update payload for a single row. Each parameter is described below.

    Name

    Type

    Description

    tableName (required)

    String

    Name of the data table to update.

    primaryKey (required)

    PrimaryKey

    Primary key information, including primary key column names and values.

    • Supported data types for primary key columns: STRING, INTEGER, and BINARY.

    • The number and types of primary key columns must match the table schema.

    columnsToUpdate (required)

    List<Pair<Column, Type>>

    List of attribute column changes. Call the following RowUpdateChange methods to add change operations:

    • put: add or modify an attribute column.

    • deleteColumn: delete a specified version of an attribute column.

    • deleteColumns: delete all versions of an attribute column.

    For code samples of each operation, see the Scenarios section.

    condition (optional)

    Condition

    Specifies the write condition. For details, see Conditional update.

    Scenarios

    Write attribute columns with a specified version number

    Pass a third argument to put to specify the version number (a millisecond timestamp) for the attribute column. Use this approach to archive historical values keyed to business time.

    String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
// Specify the version number (a millisecond timestamp) as the third argument.
long version = System.currentTimeMillis();
rowUpdateChange.put("col2", ColumnValue.fromString("val2"), version);

client.updateRow(new UpdateRowRequest(rowUpdateChange));

    Delete a specified version of an attribute column

    Use deleteColumn to remove a single version of an attribute column while keeping all other versions intact.

    String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
// Delete the col2 value at the specified version (a millisecond timestamp).
rowUpdateChange.deleteColumn("col2", 1747893563831L);

client.updateRow(new UpdateRowRequest(rowUpdateChange));

    Delete an entire attribute column

    Use deleteColumns to delete every version of an attribute column in a single operation.

    String tableName = "update_row_demo";

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

RowUpdateChange rowUpdateChange = new RowUpdateChange(tableName, primaryKey);
// Delete all versions of the col2 attribute column.
rowUpdateChange.deleteColumns("col2");

client.updateRow(new UpdateRowRequest(rowUpdateChange));

    References