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

Java SDK 在单次请求内批量读取一张或多张数据表的多行数据，按行独立返回结果，适用于批量按主键拉取明细的场景。

前提条件

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

功能说明

public BatchGetRowResponse batchGetRow(BatchGetRowRequest batchGetRowRequest) throws TableStoreException, ClientException

在单次请求内批量读取多行数据。BatchGetRowRequest 通过 addMultiRowQueryCriteria 添加 MultiRowQueryCriteria，每个 MultiRowQueryCriteria 对应一张表的查询条件，同一表内所有行采用相同条件（版本数、列、过滤器等）。

服务端按行独立处理，单行失败不影响其他行的执行结果，通过 isAllSucceed / getSucceedRows / getFailedRows 获取行级结果。

以下示例从数据表 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("RequestId: " + response.getRequestId());
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());
    }
}

说明

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

关键参数：

tableName（必选）：读取的数据表名称。
rowKeys（必选）：主键列表，通过 addRow 添加。
maxVersions 或 timeRange（二选一）：最大版本数或数据版本范围。

参数说明

通过 MultiRowQueryCriteria 携带单张表的批量查询条件，各参数说明如下。

名称	类型	说明
tableName（必选）	String	读取的数据表名称。
rowKeys（必选）	List<PrimaryKey>	主键列表，通过 `addRow(PrimaryKey)` 添加；同一表内所有行采用相同查询条件。
maxVersions（二选一）	OptionalValue<Integer>	最大版本数。`maxVersions` 和 `timeRange` 必须至少设置一个。如果符合查询条件的数据版本数量超过设置的最大版本数，按从新到旧的顺序返回指定版本数量的数据。
timeRange（二选一）	OptionalValue<TimeRange>	数据版本范围。`maxVersions` 和 `timeRange` 必须至少设置一个。数据表的每个属性列可以有不同的数据版本，设置版本范围后仅返回该范围内的数据。
columnsToGet（可选）	Set<String>	指定读取的数据列，可以是主键列或属性列。不设置 `columnsToGet` 时，返回整行数据。设置后如果读取的行数据不包含任何指定的数据列，将返回 null。
filter（可选）	OptionalValue<Filter>	过滤条件，详情请参见过滤器。如果同时设置 `columnsToGet` 和 `filter`，先按 `columnsToGet` 筛选数据列，再按 `filter` 条件过滤数据。

场景示例

跨表批量读取

每张表对应一个 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);