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

前提条件

安装 Tablestore Java SDK并初始化客户端。

功能说明

调用 getRange 按主键范围正向或反向读取连续多行数据，可指定返回列、数据版本范围和过滤条件。

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

说明

单次范围读取最多返回 5000 行或 4 MB 数据。达到任一限制时，可使用响应中的 nextStartPrimaryKey 继续读取。

以下示例从数据表 get_range_demo 正向读取主键值大于等于 row1 的所有行，仅返回每列最新版本。

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

// 起始主键（包含）
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

// 结束主键（不包含），INF_MAX 表示无限大
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);
}

参数说明

GetRangeRequest 包含以下参数。

名称

类型

说明

rangeRowQueryCriteria（必选）

RangeRowQueryCriteria

范围读取条件。

transactionId（可选）

String

局部事务 ID。仅在局部事务内读取数据时设置。

关于如何获取和使用该 ID，请参见局部事务。

范围读取条件

rangeRowQueryCriteria 的类型为 RangeRowQueryCriteria，包含以下参数。

名称	类型	说明
tableName（必选）	`String`	数据表名称。
inclusiveStartPrimaryKey（必选）	`PrimaryKey`	起始主键，返回结果包含该主键。正向读取时必须小于结束主键，反向读取时必须大于结束主键。主键结构必须与数据表一致，可使用 `PrimaryKeyValue.INF_MIN` 和 `PrimaryKeyValue.INF_MAX` 表示无限小和无限大。
exclusiveEndPrimaryKey（必选）	`PrimaryKey`	结束主键，返回结果不包含该主键。主键结构必须与数据表一致，可使用 `PrimaryKeyValue.INF_MIN` 和 `PrimaryKeyValue.INF_MAX` 表示无限小和无限大。
direction（可选）	`Direction`	读取方向。默认值为 `FORWARD`，表示正向读取；`BACKWARD` 表示反向读取。
maxVersions（可选）	`Integer`	每个属性列最多返回的数据版本数。如果符合条件的数据版本数超出该值，按版本号从新到旧返回。`maxVersions` 和 `timeRange` 必须至少设置一个。
timeRange（可选）	`TimeRange`	数据版本范围。仅返回该范围内的数据版本。`maxVersions` 和 `timeRange` 必须至少设置一个。
limit（可选）	`Integer`	单次最多返回的行数，必须大于 0。达到该值时，可使用响应中的 `nextStartPrimaryKey` 继续读取。
columnsToGet（可选）	`Set<String>`	要返回的列名称。不设置时返回整行；设置后，不返回不包含任何指定列的行。
filter（可选）	`Filter`	过滤条件。同时设置 `columnsToGet` 和 `filter` 时，先筛选返回列，再对结果应用过滤条件。关于过滤条件的配置方法，请参见过滤器。

返回值

GetRangeResponse 包含以下业务字段。

字段	类型	说明
`rows`	`List<Row>`	本次读取返回的行数据，通过 `getRows` 获取。
`nextStartPrimaryKey`	`PrimaryKey`	下一次读取的起始主键，通过 `getNextStartPrimaryKey` 获取。当前范围已全部读取时返回 `null`。

场景示例

分页迭代读取

单次响应最多返回 5000 行或 4 MB。响应中的 nextStartPrimaryKey 为下一页起始主键，循环调用直至返回 null 即扫完全部数据。

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

    // 单次响应未读完，使用 nextStartPrimaryKey 继续下一页
    PrimaryKey nextStart = response.getNextStartPrimaryKey();
    if (nextStart == null) {
        break;
    }
    criteria.setInclusiveStartPrimaryKey(nextStart);
}
System.out.println("Total rows scanned: " + totalRows);

反向读取

通过 setDirection(Direction.BACKWARD) 反向扫描。反向读取时起始主键必须大于结束主键。

String tableName = "get_range_demo";

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

// 反向读取时，起始主键必须大于结束主键
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());

条件过滤读取

通过 setFilter 设置列值过滤条件，仅返回符合条件的行。

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

// 仅返回 col1 等于 "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());