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

本文介绍如何通过 Java SDK 范围读取表格存储中的数据。

前提条件

方法说明

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

GetRangeRequest参数说明

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（可选）	OptionalValue<Integer>	最大版本数。必须设置最大版本数和版本范围的其中一个。如果符合查询条件的数据版本数量超过设置的最大版本数，按从新到旧的顺序返回指定版本数量的数据。
timeRange（可选）	OptionalValue<TimeRange>	数据版本范围。必须设置最大版本数和版本范围的其中一个。表格存储数据表的每个属性列可以有不同的数据版本，设置版本范围后，仅返回版本范围内的数据。
limit（可选）	int	单次返回最大行数，必须大于 0。如果符合查询条件的数据行数大于设置的值，将返回指定的最大行数和用于下一次查询的起始主键值。
columnsToGet（可选）	Set<String>	指定读取的数据列，可以是主键列或属性列。不设置columnsToGet时，返回整行数据。设置columnsToGet时，如果读取的行数据不包含任何指定的数据列，不返回该行数据。
filter（可选）	OptionalValue<Filter>	过滤条件，详情请参见过滤器。如果同时设置columnsToGet和filter，先按columnsToGet筛选符合条件的数据行，再按filter条件过滤数据。

示例代码

以下示例代码用于读取 test_table 表中主键值大于 row1 的数据。

public static void getRangeExample(SyncClient client) {
    // 构造查询条件
    RangeRowQueryCriteria rangeRowQueryCriteria = new RangeRowQueryCriteria("test_table");
    // 设置查询起始主键
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
    rangeRowQueryCriteria.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());
    // 设置查询结束主键，返回结果不包含结束主键
    primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
    rangeRowQueryCriteria.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());
    // 设置查询版本
    rangeRowQueryCriteria.setMaxVersions(1);

    // 调用 getRange 方法查询数据
    GetRangeRequest getRangeRequest = new GetRangeRequest(rangeRowQueryCriteria);
    GetRangeResponse getRangeResponse = client.getRange(getRangeRequest);

    // 返回结果处理
    System.out.println("RequestId: " + getRangeResponse.getRequestId());
    System.out.println("Read CU Cost: " + getRangeResponse.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
    System.out.println("Write CU Cost: " + getRangeResponse.getConsumedCapacity().getCapacityUnit().getWriteCapacityUnit());
    for(Row row : getRangeResponse.getRows())
        System.out.println(row);
}

单次范围扫描数据上限为 5000 行或者 4 MB，超出限制部分的数据将返回用于下一次读取的起始主键值，您可以参考以下代码进行迭代查询。

while(true) {
    GetRangeRequest getRangeRequest = new GetRangeRequest(rangeRowQueryCriteria);
    GetRangeResponse getRangeResponse = client.getRange(getRangeRequest);

    // 返回结果处理
    System.out.println("RequestId: " + getRangeResponse.getRequestId());
    System.out.println("Read CU Cost: " + getRangeResponse.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
    System.out.println("Write CU Cost: " + getRangeResponse.getConsumedCapacity().getCapacityUnit().getWriteCapacityUnit());
    for(Row row : getRangeResponse.getRows())
        System.out.println(row);
    System.out.println("Rows Count: " + getRangeResponse.getRows().size());

    // 设置下一次读取数据起始主键
    if(getRangeResponse.getNextStartPrimaryKey() != null)
        rangeRowQueryCriteria.setInclusiveStartPrimaryKey(getRangeResponse.getNextStartPrimaryKey());
    else break;
}

您也可以在查询数据时参考示例代码进行以下设置。

设置数据读取方向。

// 设置反向读取数据
rangeRowQueryCriteria.setDirection(Direction.BACKWARD);
// 设置查询起始主键，反向读取数据时，起始主键要大于结束主键
PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
rangeRowQueryCriteria.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());
// 设置查询结束主键，返回结果不包含结束主键
primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
rangeRowQueryCriteria.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());

设置读取的数据版本范围，结果只返回版本范围内的数据。

// 设置查询的数据版本范围为当前时间往前一天
rangeRowQueryCriteria.setTimeRange(new TimeRange(System.currentTimeMillis() - 86400*1000, System.currentTimeMillis()));

指定读取的属性列。

rangeRowQueryCriteria.addColumnsToGet("col2");

设置单次返回最大行数。
```
rangeRowQueryCriteria.setLimit(10);
```

前提条件

方法说明

示例代码

相关文档