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

前提条件

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

功能说明

调用 batchGetRow 批量读取多行数据。每张表使用一个 MultiRowQueryCriteria，同一条件中的所有行共用版本、返回列和过滤器等设置。

服务端按行独立处理请求，单行失败不影响其他行。可通过 isAllSucceed、getSucceedRows 和 getFailedRows 判断执行结果。

public BatchGetRowResponse batchGetRow(BatchGetRowRequest batchGetRowRequest) throws TableStoreException, ClientException

说明

单次批量读取最多支持 100 行数据。

以下示例从数据表 batch_get_demo 读取主键值为 row1 和 row2 的两行数据，仅返回每列最新版本。

String tableName = "batch_get_demo";

MultiRowQueryCriteria criteria = new MultiRowQueryCriteria(tableName);

// 添加第 1 行主键
PrimaryKeyBuilder pkb1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb1.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.addRow(pkb1.build());

// 添加第 2 行主键
PrimaryKeyBuilder pkb2 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb2.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row2"));
criteria.addRow(pkb2.build());

criteria.setMaxVersions(1);

BatchGetRowRequest request = new BatchGetRowRequest();
request.addMultiRowQueryCriteria(criteria);

BatchGetRowResponse response = client.batchGetRow(request);
System.out.println("All Succeeded: " + response.isAllSucceed());

for (BatchGetRowResponse.RowResult rowResult : response.getSucceedRows()) {
    System.out.println("Succeeded: " + rowResult.getRow());
}
if (!response.isAllSucceed()) {
    for (BatchGetRowResponse.RowResult fail : response.getFailedRows()) {
        System.out.println("Failed: table=" + fail.getTableName()
                + " index=" + fail.getIndex()
                + " error=" + fail.getError());
    }
}

参数说明

BatchGetRowRequest 包含以下参数。

名称	类型	说明
criteriasGroupByTable（必选）	`Map<String, MultiRowQueryCriteria>`	按数据表组织的批量读取条件。每张表添加一个 `MultiRowQueryCriteria`，同一条件中的所有行共用版本、返回列和过滤器等设置。

单表批量读取条件

criteriasGroupByTable 中每个值的类型为 MultiRowQueryCriteria，包含以下参数。

名称	类型	说明
tableName（必选）	`String`	数据表名称。
rowKeys（必选）	`List<PrimaryKey>`	要读取的行主键列表，通过 `addRow` 添加。每个主键必须包含数据表的全部主键列，且列名称、顺序和类型必须与数据表的主键结构一致。
maxVersions（可选）	`Integer`	每个属性列最多返回的数据版本数。如果符合条件的数据版本数超出该值，按版本号从新到旧返回。`maxVersions` 和 `timeRange` 必须至少设置一个。
timeRange（可选）	`TimeRange`	数据版本范围。仅返回该范围内的数据版本。`maxVersions` 和 `timeRange` 必须至少设置一个。
columnsToGet（可选）	`Set<String>`	要返回的列名称。不设置时返回整行；设置后，如果行中不包含任何指定列，则该行结果中的 `row` 为 `null`。
filter（可选）	`Filter`	过滤条件。同时设置 `columnsToGet` 和 `filter` 时，先筛选返回列，再对结果应用过滤条件。关于过滤条件的配置方法，请参见过滤器。

返回值

BatchGetRowResponse 包含以下业务字段。

字段	类型	说明
`tableToRowsResult`	`Map<String, List<RowResult>>`	按数据表组织的行级结果，通过 `getTableToRowsResult` 获取。也可通过 `getSucceedRows` 和 `getFailedRows` 分别获取成功和失败的行级结果。

行级结果

tableToRowsResult 中的每个元素为 RowResult，包含以下字段。

字段	类型	说明
`isSucceed`	`boolean`	当前行是否读取成功。
`tableName`	`String`	数据表名称。
`row`	`Row`	读取到的行数据。行不存在或不满足过滤条件时为 `null`。
`error`	`Error`	当前行读取失败时的错误信息。
`index`	`int`	当前行在对应 `MultiRowQueryCriteria` 中的位置。

场景示例

跨表批量读取

每张表对应一个 MultiRowQueryCriteria，通过 addMultiRowQueryCriteria 加入同一请求，单次请求即可读取多张表的数据。

String tableA = "batch_get_demo";
String tableB = "batch_get_demo_2";

BatchGetRowRequest request = new BatchGetRowRequest();

// 表 A 的查询条件
MultiRowQueryCriteria criteriaA = new MultiRowQueryCriteria(tableA);
PrimaryKeyBuilder pkA = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkA.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteriaA.addRow(pkA.build());
criteriaA.setMaxVersions(1);
request.addMultiRowQueryCriteria(criteriaA);

// 表 B 的查询条件
MultiRowQueryCriteria criteriaB = new MultiRowQueryCriteria(tableB);
PrimaryKeyBuilder pkB = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkB.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("rowA"));
criteriaB.addRow(pkB.build());
criteriaB.setMaxVersions(1);
request.addMultiRowQueryCriteria(criteriaB);

BatchGetRowResponse response = client.batchGetRow(request);
System.out.println("Total succeeded rows: " + response.getSucceedRows().size());

条件过滤读取

通过 setFilter 设置列值过滤条件，同一表内所有行共用该条件，仅返回符合条件的行。

String tableName = "batch_get_demo";

MultiRowQueryCriteria criteria = new MultiRowQueryCriteria(tableName);

PrimaryKeyBuilder pkb1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb1.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.addRow(pkb1.build());
PrimaryKeyBuilder pkb2 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb2.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row2"));
criteria.addRow(pkb2.build());

criteria.setMaxVersions(1);

// 仅返回 col1 等于 "val1" 的行
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
filter.setPassIfMissing(false);
criteria.setFilter(filter);

BatchGetRowRequest request = new BatchGetRowRequest();
request.addMultiRowQueryCriteria(criteria);

BatchGetRowResponse response = client.batchGetRow(request);
int matched = 0;
for (BatchGetRowResponse.RowResult rowResult : response.getSucceedRows()) {
    if (rowResult.getRow() != null) {
        matched++;
    }
}
System.out.println("Rows matching filter: " + matched);