All Products
Search

This Product

    Tablestore:Write a single row of data

    Document Center

    Tablestore:Write a single row of data

    Last Updated:Jun 30, 2025

    This topic describes how to write a single row of data to a Tablestore table by using Tablestore SDK for Java.

    Prerequisites

    A client is initialized. For more information, see Initialize a Tablestore client.

    Method

    public PutRowResponse putRow(PutRowRequest putRowRequest) throws TableStoreException, ClientException

    PutRowRequest parameters

    • rowChange (required) RowPutChange: The information about the row to write. The following table describes the parameters that specify the information.

      Parameter

      Type

      Description

      tableName (required)

      String

      The name of the data table.

      primaryKey (required)

      PrimaryKey

      The primary key information, including the primary key column names and values.

      • The data types of primary key columns include STRING, INTEGER, and BINARY.

      • The number and types of primary keys that you specify must be consistent with those defined in the table.

      • When a primary key column is specified as an auto-increment primary key column, you must set the value of the column to a placeholder. For more information, see Auto-increment primary key column.

      columnsToPut (optional)

      List<Column>

      The attribute column information, including the attribute column names, values, and version numbers.

      • The data types of attribute columns include STRING, INTEGER, BINARY, DOUBLE, and BOOLEAN.

      • The version number is a timestamp that is automatically generated by the system by default or can be specified by you. For more information, see Data versions and TTL.

      condition (optional)

      Condition

      The write condition. For more information, see Perform conditional updates.

      returnType (optional)

      ReturnType

      The return type.

      • RT_NONE: default value, no data is returned.

      • RT_PK: returns the primary key columns, which can be used for auto-increment primary key columns.

      • RT_AFTER_MODIFY: returns the modified column values, which is used for atomic counters.

    Sample code

    The following sample code writes a row of data to the test_table table. The primary key value of this row is row1.

    public static void putRowExample(SyncClient client) {
    // Construct the primary key.
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();

    // Construct the row data to write.
    RowPutChange rowPutChange = new RowPutChange("test_table", primaryKey);

    // Call the putRow method to write the row data.
    PutRowRequest putRowRequest = new PutRowRequest(rowPutChange);
    PutRowResponse putRowResponse = client.putRow(putRowRequest);

    // Return the result.
    System.out.println("* RequestId: " + putRowResponse.getRequestId());
    System.out.println("* Read CU Cost: " + putRowResponse.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
    System.out.println("* Write CU Cost: " + putRowResponse.getConsumedCapacity().getCapacityUnit().getWriteCapacityUnit());
}

    • Add attribute columns.

      rowPutChange.addColumn("col1", ColumnValue.fromString("val1"));

    • Specify the version number. You can specify a separate version number for each attribute column.

      // Use the current timestamp as the version number.
rowPutChange.addColumn("col1", ColumnValue.fromString("val1"), System.currentTimeMillis());

    References