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

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Description

Call getRow to read a row by its complete primary key. You can specify the returned columns, data version range, and filter conditions.

public GetRowResponse getRow(GetRowRequest getRowRequest) throws TableStoreException, ClientException

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("Row: " + response.getRow());

Parameters

GetRowRequest contains the following parameters.

Name	Type	Description
rowQueryCriteria (required)	`SingleRowQueryCriteria`	The criteria for reading a row.
transactionId (optional)	`String`	The local transaction ID. Set this parameter only when you read data in a local transaction.

Single-row query criteria

rowQueryCriteria is of the SingleRowQueryCriteria 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. Specify all primary key columns in the same order and with the same types as the table schema. Primary key columns support the `STRING`, `INTEGER`, and `BINARY` types. If the primary key contains an auto-increment column, specify its actual value.
maxVersions (optional)	`Integer`	The maximum number of data versions to return. If more versions match, Tablestore returns versions from newest to oldest. Set at least one of `maxVersions` and `timeRange`.
timeRange (optional)	`TimeRange`	The data version range. Only versions in the range are returned. Set at least one of `maxVersions` and `timeRange`.
columnsToGet (optional)	`Set<String>`	The columns to return. If you do not specify this parameter, the entire row is returned. If you specify it and the row contains none of the specified columns, `null` is returned.
filter (optional)	`Filter`	The filter condition. If you specify both `columnsToGet` and `filter`, Tablestore first selects the returned columns and then applies the filter.

Response

GetRowResponse contains the following operation-specific field.

Field	Type	Description
`row`	`Row`	The queried row, obtained by calling `getRow`. If the row does not exist or does not meet the filter condition, `null` is returned.

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