All Products
Search

This Product

    Tablestore:Read a row

    Document Center

    Tablestore:Read a row

    Last Updated:Jun 25, 2026

    Tablestore SDK for Java reads a single row from a data table by primary key. Use the request options to limit returned columns, restrict the version range, or filter on column values.

    Prerequisites

    Install the Tablestore SDK for Java and initialize the client.

    Method definition

    public GetRowResponse getRow(GetRowRequest getRowRequest) throws TableStoreException, ClientException

    Reads a single row from a data table by primary key. Specify query conditions in SingleRowQueryCriteria and retrieve the result with response.getRow().

    Note

    Set at least one of maxVersions or timeRange. Otherwise, the server returns a parameter error.

    The following example reads the row with primary key row1 from the get_row_demo table and returns only the latest version of each column.

    String tableName = "get_row_demo";

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

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);
criteria.setMaxVersions(1);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Read CU: " + response.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
System.out.println("Row: " + response.getRow());

    Parameters

    Configure the following parameters in SingleRowQueryCriteria:

    Name

    Type

    Description

    tableName (required)

    String

    The name of the data table to read from.

    primaryKey (required)

    PrimaryKey

    The primary key columns and their values.

    • Supported primary key column types are STRING, INTEGER, and BINARY.

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

    • If the table has an auto-increment column, provide the full primary key with the actual value of that column.

    maxVersions (one of two)

    OptionalValue<Integer>

    The maximum number of versions to return. Set at least one of maxVersions or timeRange.

    Returns up to this many versions, from newest to oldest.

    timeRange (one of two)

    OptionalValue<TimeRange>

    The version range to return. Set at least one of maxVersions or timeRange.

    Each attribute column can have multiple versions. Setting a version range returns only versions within that range.

    columnsToGet (optional)

    Set<String>

    The columns to read. The list can include primary key columns and attribute columns.

    • If columnsToGet is not set, the entire row is returned.

    • If columnsToGet is set but the row contains none of the specified columns, Tablestore returns null.

    filter (optional)

    OptionalValue<Filter>

    The filter condition. For more information, see Filters.

    When you set both columnsToGet and filter, Tablestore first selects columns by columnsToGet, then applies filter.

    Examples

    Read specific attribute columns

    Use addColumnsToGet to specify the attribute column names to read. Only those columns are returned.

    String tableName = "get_row_demo";

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

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);
criteria.setMaxVersions(1);

// Read only col1 and col2
criteria.addColumnsToGet("col1");
criteria.addColumnsToGet("col2");

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("Row (selected columns): " + response.getRow());

    Read by version range

    Use setTimeRange to specify a version time range. Only versions within the range are returned.

    String tableName = "get_row_demo";

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

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);

// Read all versions from the past day
long now = System.currentTimeMillis();
criteria.setTimeRange(new TimeRange(now - 86400 * 1000L, now));
criteria.setMaxVersions(Integer.MAX_VALUE);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("Row (time range): " + response.getRow());

    Read with a filter

    Use setFilter to set a column value filter. Tablestore returns the row only when it matches the filter condition.

    String tableName = "get_row_demo";

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

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);
criteria.setMaxVersions(1);

// Return the row only when col1 equals "val1"
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
// Skip the row when the column is missing
filter.setPassIfMissing(false);
criteria.setFilter(filter);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("Row (filtered): " + response.getRow());

    References