Table Store Java SDK 離線讀取資料 - 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);