表格存储 Java SDK 离线读取 - 表格存储

前提条件

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

功能说明

public BulkExportResponse bulkExport(BulkExportRequest bulkExportRequest) throws TableStoreException, ClientException

按主键范围扫描数据表中的连续多行（左闭右开区间，正序返回大于等于起始主键且小于结束主键的所有行）。通过 BulkExportQueryCriteria 配置起始和结束主键、返回列、过滤器和数据块编码类型；返回结果以编码后的字节形式承载，需通过对应 parser 解析为行列表。

BulkExportQueryCriteria(String tableName) 构造查询条件，位于 com.alicloud.openservices.tablestore.model.tunnel 子包。
setDataBlockType(DataBlockType) 指定返回数据块编码类型：DBT_PLAIN_BUFFER 对应 PlainBufferBlockParser，DBT_SIMPLE_ROW_MATRIX 对应 SimpleRowMatrixBlockParser。
BulkExportResponse.getRows() 返回 ByteBuffer 类型，通过对应的 parser 解析为 List<Row>。
BulkExportResponse.getNextStartPrimaryKey() 返回下一次读取的起始主键；不为 null 表示数据未读完，需以该值作为新的起始主键继续调用。

以下示例按主键范围 [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));

参数说明

名称	类型	说明
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 匹配。

场景示例

按 nextStartPrimaryKey 分页读取全表

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

前提条件

功能说明

参数说明

场景示例

按 nextStartPrimaryKey 分页读取全表

相关文档