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

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Description

Call getRange to read consecutive rows in forward or reverse order within a primary key range. You can specify the returned columns, data version range, and filter conditions.

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

Note

A single range read returns at most 5,000 rows or 4 MB of data. When either limit is reached, use nextStartPrimaryKey in the response to continue reading.

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.

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));
for (Row row : response.getRows()) {
    System.out.println(row);
}

Parameters

GetRangeRequest contains the following parameters.

Name

Type

Description

rangeRowQueryCriteria (required)

RangeRowQueryCriteria

The criteria for reading a range of rows.

transactionId (optional)

String

The local transaction ID. Set this parameter only when you read data in a local transaction.

For information about how to obtain and use the ID, see Use local transactions.

Range query criteria

rangeRowQueryCriteria is of the RangeRowQueryCriteria type and contains the following parameters.

Name	Type	Description
tableName (required)	`String`	The name of the table.
inclusiveStartPrimaryKey (required)	`PrimaryKey`	The inclusive start primary key. For forward reads, it must be less than the end primary key. For reverse reads, it must be greater than the end primary key. Its schema must match the table schema. Use `PrimaryKeyValue.INF_MIN` and `PrimaryKeyValue.INF_MAX` to represent negative and positive infinity.
exclusiveEndPrimaryKey (required)	`PrimaryKey`	The exclusive end primary key. Its schema must match the table schema. Use `PrimaryKeyValue.INF_MIN` and `PrimaryKeyValue.INF_MAX` to represent negative and positive infinity.
direction (optional)	`Direction`	The read direction. The default value is `FORWARD`. Set this parameter to `BACKWARD` for reverse reads.
maxVersions (optional)	`Integer`	The maximum number of data versions to return for each attribute column. 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`.
limit (optional)	`Integer`	The maximum number of rows to return in one call. The value must be greater than 0. When the limit is reached, use `nextStartPrimaryKey` in the response to continue reading.
columnsToGet (optional)	`Set<String>`	The columns to return. If you do not specify this parameter, the entire row is returned. If you specify it, rows that contain none of the specified columns are not 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. For information about how to configure the filter, see Use filters.

Response

GetRangeResponse contains the following operation-specific fields.

Field	Type	Description
`rows`	`List<Row>`	The rows returned in the current call, obtained by calling `getRows`.
`nextStartPrimaryKey`	`PrimaryKey`	The start primary key for the next call, obtained by calling `getNextStartPrimaryKey`. If the range has been completely read, `null` is returned.

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