All Products
Search

This Product

    Tablestore:Read rows with an iterator

    Document Center

    Tablestore:Read rows with an iterator

    Last Updated:Jun 25, 2026

    Tablestore SDK for Java provides an iterator that reads multiple rows within a primary key range. The iterator issues paginated requests automatically, which is useful for large-range scans that process rows one at a time.

    Prerequisites

    Install the Tablestore SDK for Java and initialize the client.

    Description

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

    Creates an iterator over a primary key range and returns a standard Java Iterator<Row>. Each call to iterator.next() returns a row from an internal buffer and issues the next batch request when the buffer is empty. You do not need to track nextStartPrimaryKey or loop over getRange manually.

    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 (required, one of maxVersions or timeRange)

    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 (required, one of maxVersions or timeRange)

    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.

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

    References