Table Store Java SDK 離線讀取 - Tablestore

前提條件

安裝 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 分頁讀取全表

相關文檔