表格存储 Java SDK迭代读取数据-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

方法说明

createRangeIterator 返回一个 Java Iterator<Row>，用于迭代读取指定范围内的数据行。迭代器自动处理底层分批请求——每次调用 iterator.next() 时，SDK 透明地从缓冲区取数据并在必要时发起下一批请求，无需手动管理翻页 token 或循环调用 getRange。

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

RangeIteratorParameter 参数概览：

3 个必填参数：tableName、inclusiveStartPrimaryKey、exclusiveEndPrimaryKey
版本控制（二选一）：maxVersions 或 timeRange，必须指定其中一个
读取方向：direction，默认 FORWARD；设为 BACKWARD 时，起始主键必须大于结束主键
行数控制：maxCount 限制迭代器返回的总行数；bufferSize 控制每次底层请求拉取的行数

列过滤：columnsToGet 指定返回的列；filter 在服务端过滤数据

RangeIteratorParameter参数说明

名称	类型	说明
tableName（必选）	String	数据表名称。
inclusiveStartPrimaryKey（必选）	PrimaryKey	起始主键（含）。返回结果包含该行数据。主键列的数量和类型必须与数据表结构一致。正向读取时，起始主键必须小于结束主键；反向读取时，起始主键必须大于结束主键。方向约束不满足时请求失败。 `PrimaryKeyValue.INF_MIN` 表示无限小，`PrimaryKeyValue.INF_MAX` 表示无限大。
exclusiveEndPrimaryKey（必选）	PrimaryKey	结束主键（不含）。返回结果不包含该行数据。主键列的数量和类型必须与数据表结构一致。 `PrimaryKeyValue.INF_MIN` 表示无限小，`PrimaryKeyValue.INF_MAX` 表示无限大。
direction（可选）	Direction	读取方向，默认值为 `FORWARD`。 `FORWARD`：按主键升序正向读取数据。 `BACKWARD`：按主键降序反向读取数据。设置反向读取时，起始主键必须大于结束主键。
maxVersions（可选）	OptionalValue<Integer>	每个属性列返回的最大版本数。`maxVersions` 和 `timeRange` 必须指定其中一个。若某列的版本数超过设置值，按版本从新到旧的顺序返回指定数量的版本。
timeRange（可选）	OptionalValue<TimeRange>	读取的版本范围。`maxVersions` 和 `timeRange` 必须指定其中一个。只返回指定时间范围内写入的数据版本。
maxCount（可选）	int	迭代器返回的最大总行数，必须大于 0。
bufferSize（可选）	int	每次底层请求拉取的行数，必须大于 0。适当减小此值可降低大数据量场景下的内存占用。当前批次数据耗尽后，迭代器自动从上次断点发起下一次请求。
columnsToGet（可选）	Set<String>	指定返回的列，可以是主键列或属性列。不设置时，返回所有列。设置后，若某行不包含任何指定列，该行不返回。
filter（可选）	OptionalValue<Filter>	服务端过滤条件，详情请参见过滤器。同时设置 `columnsToGet` 和 `filter` 时，先按 `columnsToGet` 筛选列，再按 `filter` 过滤数据。

示例代码

以下示例从 test_table 表的主键 row1 开始，正向读取到表末尾的所有数据行。

public static void createRangeIteratorExample(SyncClient client) {
    // 1. 初始化迭代查询参数，指定目标表名
    RangeIteratorParameter rangeIteratorParameter = new RangeIteratorParameter("test_table");

    // 2. 设置起始主键（含）：从 row1 开始读取
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
    rangeIteratorParameter.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());

    // 3. 设置结束主键（不含）：INF_MAX 表示读取到表末尾
    primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
    rangeIteratorParameter.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());

    // 4. 每个属性列只返回最新版本
    rangeIteratorParameter.setMaxVersions(1);

    // 5. 迭代读取所有匹配行，SDK 自动分批拉取，无需处理翻页逻辑
    Iterator<Row> iterator = client.createRangeIterator(rangeIteratorParameter);
    while (iterator.hasNext()) {
        Row row = iterator.next();
        System.out.println(row);
    }
}

以下代码片段展示各可选参数的独立配置方式。

设置数据读取方向。

// 反向读取时，起始主键必须大于结束主键
rangeIteratorParameter.setDirection(Direction.BACKWARD);

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
rangeIteratorParameter.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());

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

按版本时间范围过滤，只返回范围内的数据版本。

// 只返回最近 24 小时内写入的数据版本
rangeIteratorParameter.setTimeRange(new TimeRange(System.currentTimeMillis() - 86400 * 1000, System.currentTimeMillis()));

限制迭代器返回的最大总行数。
```
rangeIteratorParameter.setMaxCount(20);
```
设置每次底层请求的拉取行数。
```
rangeIteratorParameter.setBufferSize(5);
```

指定返回的属性列。

rangeIteratorParameter.addColumnsToGet("col2");

前提条件

方法说明

示例代码

相关文档