Read rows with an iterator - Tablestore SDK for Java - Tablestore

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Description

Call the createRangeIterator method to create a row iterator for a specified primary key range. When the current batch is exhausted, the iterator automatically issues the next request. You do not need to track nextStartPrimaryKey or loop over getRange.

public Iterator<Row> createRangeIterator(RangeIteratorParameter rangeIteratorParameter) throws TableStoreException, ClientException

The following example iterates forward through the range_iter_demo table, starting at primary key row1 and continuing to the end of the table, printing each row.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

// End primary key (exclusive). INF_MAX reads to the end of the table.
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setExclusiveEndPrimaryKey(endPkBuilder.build());

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
int count = 0;
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
    count++;
}
System.out.println("Total rows iterated: " + count);

Parameters

Use RangeIteratorParameter to carry the iteration query conditions. The parameters are described below.

Name	Type	Description
tableName (required)	String	The name of the table to read.
inclusiveStartPrimaryKey (required)	PrimaryKey	The start primary key, including 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 table schema. For forward iteration, the start primary key must be less than the end primary key. For backward iteration, the start primary key must be greater than the end primary key. Use `PrimaryKeyValue.INF_MIN` for negative infinity and `PrimaryKeyValue.INF_MAX` for positive infinity.
exclusiveEndPrimaryKey (required)	PrimaryKey	The end primary key, including primary key column names and values. The returned data does not include the end primary key. The number and types of primary key columns must match the table schema. Use `PrimaryKeyValue.INF_MIN` for negative infinity and `PrimaryKeyValue.INF_MAX` for positive infinity.
direction (optional)	Direction	The read direction. `FORWARD`: the default. Iterates forward. `BACKWARD`: iterates backward.
maxVersions (optional)	OptionalValue<Integer>	The maximum number of versions returned per attribute column. You must set at least one of `maxVersions` and `timeRange`. If matching versions exceed this maximum, Tablestore returns the most recent versions in newest-to-oldest order, up to the maximum.
timeRange (optional)	OptionalValue<TimeRange>	The version range. You must set at least one of `maxVersions` and `timeRange`. Each attribute column can hold multiple versions. Setting a version range returns only the data within that range.
maxCount (optional)	int	The maximum total number of rows the iterator returns. Must be greater than 0.
bufferSize (optional)	int	The number of rows fetched per underlying request. Must be greater than 0. Lower this value to reduce peak memory usage during large scans. When the current batch is exhausted, the iterator automatically requests the next batch starting from where it left off.
columnsToGet (optional)	Set<String>	The columns to read. Can be primary key columns or attribute columns. If `columnsToGet` is not set, the entire row is returned. If `columnsToGet` is set and a row contains none of the specified columns, `null` is returned.
filter (optional)	OptionalValue<Filter>	The filter condition. For more information, see Use filters. If you set both `columnsToGet` and `filter`, `columnsToGet` selects the columns first, and `filter` then evaluates the rows.

Response

createRangeIterator returns an Iterator<Row>. Call hasNext() to determine whether more data is available and next() to obtain the next Row object.

Examples

Backward iteration

Use setDirection(Direction.BACKWARD) to iterate backward. For backward iteration, the start primary key must be greater than the end primary key.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);
parameter.setDirection(Direction.BACKWARD);

// For backward iteration, the start primary key must be greater than the end primary key.
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setInclusiveStartPrimaryKey(startPkBuilder.build());

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

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

Limit the total number of rows

Use setMaxCount to cap the total number of rows the iterator returns. This is useful for top-N reads and avoids unnecessary scans.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// Return at most 3 rows.
parameter.setMaxCount(3);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

Optimize memory with batch size

Use setBufferSize to control the number of rows fetched per underlying request. Lower the value to reduce peak memory usage during large scans.

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// Fetch 2 rows per underlying request.
parameter.setBufferSize(2);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}