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

前提条件

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

功能说明

调用 bulkExport 按主键范围扫描数据表中的连续多行，返回左闭右开区间内主键大于等于起始主键且小于结束主键的所有行。通过位于 com.alicloud.openservices.tablestore.model.tunnel 子包的 BulkExportQueryCriteria 配置主键范围、返回列、过滤器和数据块编码类型。返回的行数据为 ByteBuffer，需使用与编码类型匹配的 parser 解析：DBT_PLAIN_BUFFER 对应 PlainBufferBlockParser，DBT_SIMPLE_ROW_MATRIX 对应 SimpleRowMatrixBlockParser。如果 getNextStartPrimaryKey() 返回值不为 null，表示仍有数据未读取，需从该主键继续读取。

public BulkExportResponse bulkExport(BulkExportRequest bulkExportRequest) throws TableStoreException, ClientException

以下示例按主键范围 [row00, row99) 单次读取数据表 bulk_export_demo 的数据，使用 DBT_PLAIN_BUFFER 编码并通过对应 parser 解析为行列表。

String tableName = "bulk_export_demo";

// 起始主键（包含）
PrimaryKey startPk = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("row00"))
        .build();
// 结束主键（不包含）
PrimaryKey endPk = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("row99"))
        .build();

// BulkExportQueryCriteria 位于 model.tunnel 子包
BulkExportQueryCriteria criteria = new BulkExportQueryCriteria(tableName);
criteria.setInclusiveStartPrimaryKey(startPk);
criteria.setExclusiveEndPrimaryKey(endPk);
criteria.setDataBlockType(DataBlockType.DBT_PLAIN_BUFFER);
criteria.addColumnsToGet("pk");
criteria.addColumnsToGet("col1");

BulkExportRequest request = new BulkExportRequest(criteria);
BulkExportResponse response = client.bulkExport(request);

// response.getRows() 返回 ByteBuffer，通过对应 parser 解析为 List<Row>
// DBT_PLAIN_BUFFER       -> PlainBufferBlockParser
// DBT_SIMPLE_ROW_MATRIX  -> SimpleRowMatrixBlockParser
PlainBufferBlockParser parser = new PlainBufferBlockParser(response.getRows());
List<Row> rows = parser.getRows();
System.out.println("Rows returned: " + rows.size());
for (Row row : rows) {
    System.out.println(row);
}

// nextStartPrimaryKey 不为 null 表示数据未读完，需继续分页
System.out.println("Has next: " + (response.getNextStartPrimaryKey() != null));

参数说明

请求配置

BulkExportRequest 包含以下参数。

名称	类型	说明
bulkExportQueryCriteria（必选）	BulkExportQueryCriteria	范围读取条件。

范围读取条件

BulkExportRequest.bulkExportQueryCriteria 的类型为 BulkExportQueryCriteria，包含以下参数。

名称	类型	说明
tableName（必选）	String	数据表名称。
inclusiveStartPrimaryKey（必选）	PrimaryKey	读取范围的起始主键，该行存在时返回结果中会包含此行。可以是有效的主键，也可以是由 `INF_MIN`、`INF_MAX` 组成的虚拟点（虚拟点的列数必须与表主键相同）。`INF_MIN` 表示无限小，任何类型的值都比它大；`INF_MAX` 表示无限大，任何类型的值都比它小。
exclusiveEndPrimaryKey（必选）	PrimaryKey	读取范围的结束主键，该行无论是否存在都不会包含在返回结果中。取值规则与 `inclusiveStartPrimaryKey` 相同，支持有效主键或 `INF_MIN`、`INF_MAX` 虚拟点。
columnsToGet（可选）	Set<String>	要返回的列名集合。不设置则返回该行所有列。设置后，某行中指定的列均不存在时不返回该行（返回 null）；某行中部分指定列存在时，只返回存在的列。某行主键属于读取范围，但该行不包含任何指定返回的列时，返回结果中不包含该行。
filter（可选）	Filter	服务端二次过滤器。当 `columnsToGet` 和 `filter` 同时使用时，先获取 `columnsToGet` 指定的列，再在返回的列中按 `filter` 条件过滤。关于过滤条件的配置方法，请参见过滤器。
dataBlockType（可选）	DataBlockType	返回数据块的编码类型，可选 `DBT_PLAIN_BUFFER` 或 `DBT_SIMPLE_ROW_MATRIX`（API 默认 `DBT_SIMPLE_ROW_MATRIX`），需与解析时使用的 parser 匹配。

返回值

读取结果

BulkExportResponse 包含以下业务字段。

名称	类型	说明
rows	ByteBuffer	编码后的行数据。根据 `dataBlockType` 使用对应 parser 解析。
nextStartPrimaryKey	PrimaryKey	下一次读取的起始主键。为 `null` 时表示指定范围内的数据已全部返回。
dataBlockType	DataBlockType	返回行数据的编码类型。
bodyBytes	long	响应正文的字节数。

场景示例

分页读取全表

单次 bulkExport 调用通常无法读取范围内的全部数据。读取全表需以上一次响应的 nextStartPrimaryKey 作为下一次调用的起始主键，循环直到 nextStartPrimaryKey 为 null。

String tableName = "bulk_export_demo";

PrimaryKey startPk = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("row00"))
        .build();
PrimaryKey endPk = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("row99"))
        .build();

int totalRows = 0;
while (startPk != null) {
    BulkExportQueryCriteria criteria = new BulkExportQueryCriteria(tableName);
    criteria.setInclusiveStartPrimaryKey(startPk);
    criteria.setExclusiveEndPrimaryKey(endPk);
    criteria.setDataBlockType(DataBlockType.DBT_PLAIN_BUFFER);

    BulkExportResponse response = client.bulkExport(new BulkExportRequest(criteria));

    PlainBufferBlockParser parser = new PlainBufferBlockParser(response.getRows());
    List<Row> rows = parser.getRows();
    totalRows += rows.size();

    // nextStartPrimaryKey 为 null 表示已读完所有数据
    startPk = response.getNextStartPrimaryKey();
}
System.out.println("Total rows scanned: " + totalRows);