Read a range of rows - Tablestore SDK for Java - Tablestore

Prerequisites

Install Tablestore SDK for Java and initialize a SyncClient (or AsyncClient) before calling getRange.

Feature description

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

Scans consecutive rows from a data table within a primary key range. Specify the start and end primary keys in RangeRowQueryCriteria, then retrieve the returned rows from response.getRows().

The following example performs a forward scan on get_range_demo, reading all rows with a primary key greater than or equal to row1 and returning only the latest version of each column.

Note

A single range scan returns at most 5,000 rows or 4 MB. When the limit is reached, the response sets nextStartPrimaryKey to the start primary key of the next page. Call getRange in a loop to read the remaining data.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

// Start primary key (inclusive)
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

// End primary key (exclusive); INF_MAX denotes positive infinity
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Read CU: " + response.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
for (Row row : response.getRows()) {
    System.out.println(row);
}

Parameters

Pass the query conditions through RangeRowQueryCriteria. The parameters are described below.

Name	Type	Description
tableName (required)	String	The name of the data table to read from.
inclusiveStartPrimaryKey (required)	PrimaryKey	The start primary key, with the primary key column names and values. The returned data includes the start primary key. The number and types of primary key columns must match the schema of the data table. For a forward scan, the start primary key must be less than the end primary key. For a reverse scan, the start primary key must be greater than the end primary key. `PrimaryKeyValue.INF_MIN` denotes negative infinity, and `PrimaryKeyValue.INF_MAX` denotes positive infinity.
exclusiveEndPrimaryKey (required)	PrimaryKey	The end primary key, with the primary key column names and values. The returned data excludes the end primary key. The number and types of primary key columns must match the schema of the data table. `PrimaryKeyValue.INF_MIN` denotes negative infinity, and `PrimaryKeyValue.INF_MAX` denotes positive infinity.
direction (optional)	Direction	The scan direction. `FORWARD` (default): forward scan. `BACKWARD`: reverse scan.
maxVersions (one of two)	OptionalValue<Integer>	The maximum number of versions. Required if `timeRange` is not set. If the data has more versions than `maxVersions`, Tablestore returns the most recent versions in descending order.
timeRange (one of two)	OptionalValue<TimeRange>	The version range. Required if `maxVersions` is not set. Attribute columns can store multiple versions. When you set a version range, Tablestore returns only versions within that range.
limit (optional)	int	The maximum number of rows returned per call. The value must be greater than 0. If the matching data exceeds `limit`, the response contains `limit` rows plus the start primary key for the next call.
columnsToGet (optional)	Set<String>	The columns to read. Accepts primary key columns or attribute columns. If `columnsToGet` is not set, `getRange` returns the entire row. If `columnsToGet` is set and a row contains none of the specified columns, that row is excluded from the response.
filter (optional)	OptionalValue<Filter>	The filter condition. For details, see Filter. If you set both `columnsToGet` and `filter`, `getRange` first selects columns with `columnsToGet`, then filters rows with `filter`.

Scenario examples

Paginated iteration

nextStartPrimaryKey in the response is the start primary key of the next page. Call getRange in a loop until nextStartPrimaryKey is null to scan all matching rows.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

int totalRows = 0;
while (true) {
    GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
    totalRows += response.getRows().size();

    // The current response did not return all rows; use nextStartPrimaryKey to fetch the next page.
    PrimaryKey nextStart = response.getNextStartPrimaryKey();
    if (nextStart == null) {
        break;
    }
    criteria.setInclusiveStartPrimaryKey(nextStart);
}
System.out.println("Total rows scanned: " + totalRows);

Reverse scan

Use setDirection(Direction.BACKWARD) to scan in reverse. The start primary key must then be greater than the end primary key.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);
criteria.setDirection(Direction.BACKWARD);

// For a reverse scan, the start primary key must be greater than the end primary key
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (backward): " + response.getRows().size());

Conditional filtering

Use setFilter to return only rows that match a column-value condition.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

// Return only rows where col1 equals "val1"
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
filter.setPassIfMissing(false);
criteria.setFilter(filter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (filtered): " + response.getRows().size());

Tablestore:Read a range of rows