Table Store Java SDK 批量讀取資料 - Tablestore

前提條件

安裝 Tablestore Java SDK並初始化用戶端。

功能說明

調用 batchGetRow 批量讀取多行資料。每張表使用一個 MultiRowQueryCriteria，同一條件中的所有行共用版本、返回列和過濾器等設定。

服務端按行獨立處理請求，單行失敗不影響其他行。可通過 isAllSucceed、getSucceedRows 和 getFailedRows 判斷執行結果。

public BatchGetRowResponse batchGetRow(BatchGetRowRequest batchGetRowRequest) throws TableStoreException, ClientException

說明

單次批量讀取最多支援 100 行資料。

以下樣本從資料表 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("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());
    }
}

參數說明

BatchGetRowRequest 包含以下參數。

名稱	類型	說明
criteriasGroupByTable（必選）	`Map<String, MultiRowQueryCriteria>`	按資料表組織的批量讀取條件。每張表添加一個 `MultiRowQueryCriteria`，同一條件中的所有行共用版本、返回列和過濾器等設定。

單表批量讀取條件

criteriasGroupByTable 中每個值的類型為 MultiRowQueryCriteria，包含以下參數。

名稱	類型	說明
tableName（必選）	`String`	資料表名稱。
rowKeys（必選）	`List<PrimaryKey>`	要讀取的行主鍵列表，通過 `addRow` 添加。每個主鍵必須包含資料表的全部主鍵列，且列名稱、順序和類型必須與資料表的主鍵結構一致。
maxVersions（可選）	`Integer`	每個屬性列最多返回的資料版本數。如果合格資料版本數超出該值，按版本號碼從新到舊返回。`maxVersions` 和 `timeRange` 必須至少設定一個。
timeRange（可選）	`TimeRange`	資料版本範圍。僅返回該範圍內的資料版本。`maxVersions` 和 `timeRange` 必須至少設定一個。
columnsToGet（可選）	`Set<String>`	要返回的列名稱。不設定時返回整行；設定後，如果行中不包含任何指定列，則該行結果中的 `row` 為 `null`。
filter（可選）	`Filter`	過濾條件。同時設定 `columnsToGet` 和 `filter` 時，先篩選返回列，再對結果應用過濾條件。關於過濾條件的配置方法，請參見過濾器。

傳回值

BatchGetRowResponse 包含以下業務欄位。

欄位	類型	說明
`tableToRowsResult`	`Map<String, List<RowResult>>`	按資料表組織的行級結果，通過 `getTableToRowsResult` 擷取。也可通過 `getSucceedRows` 和 `getFailedRows` 分別擷取成功和失敗的行級結果。

行級結果

tableToRowsResult 中的每個元素為 RowResult，包含以下欄位。

欄位	類型	說明
`isSucceed`	`boolean`	當前行是否讀取成功。
`tableName`	`String`	資料表名稱。
`row`	`Row`	讀取到的行資料。行不存在或不滿足過濾條件時為 `null`。
`error`	`Error`	當前行讀取失敗時的錯誤資訊。
`index`	`int`	當前行在對應 `MultiRowQueryCriteria` 中的位置。

情境樣本

跨表批量讀取

每張表對應一個 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);