Table Store Java SDK 範圍讀取資料 - Tablestore

前提條件

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

功能說明

調用 getRange 按主鍵範圍正向或反向讀取連續多行資料，可指定返回列、資料版本範圍和過濾條件。

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

說明

單次範圍讀取最多返回 5000 行或 4 MB 資料。達到任一限制時，可使用響應中的 nextStartPrimaryKey 繼續讀取。

以下樣本從資料表 get_range_demo 正向讀取主索引值大於等於 row1 的所有行，僅返回每列最新版本。

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

// 起始主鍵（包含）
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

// 結束主鍵（不包含），INF_MAX 表示無限大
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
for (Row row : response.getRows()) {
    System.out.println(row);
}

參數說明

GetRangeRequest 包含以下參數。

名稱

類型

說明

rangeRowQueryCriteria（必選）

RangeRowQueryCriteria

範圍讀取條件。

transactionId（可選）

String

局部事務 ID。僅在局部事務內讀取資料時設定。

關於如何擷取和使用該 ID，請參見局部事務。

範圍讀取條件

rangeRowQueryCriteria 的類型為 RangeRowQueryCriteria，包含以下參數。

名稱	類型	說明
tableName（必選）	`String`	資料表名稱。
inclusiveStartPrimaryKey（必選）	`PrimaryKey`	起始主鍵，返回結果包含該主鍵。正向讀取時必須小於結束主鍵，反向讀取時必須大於結束主鍵。主鍵結構必須與資料表一致，可使用 `PrimaryKeyValue.INF_MIN` 和 `PrimaryKeyValue.INF_MAX` 表示無限小和無限大。
exclusiveEndPrimaryKey（必選）	`PrimaryKey`	結束主鍵，返回結果不包含該主鍵。主鍵結構必須與資料表一致，可使用 `PrimaryKeyValue.INF_MIN` 和 `PrimaryKeyValue.INF_MAX` 表示無限小和無限大。
direction（可選）	`Direction`	讀取方向。預設值為 `FORWARD`，表示正向讀取；`BACKWARD` 表示反向讀取。
maxVersions（可選）	`Integer`	每個屬性列最多返回的資料版本數。如果合格資料版本數超出該值，按版本號碼從新到舊返回。`maxVersions` 和 `timeRange` 必須至少設定一個。
timeRange（可選）	`TimeRange`	資料版本範圍。僅返回該範圍內的資料版本。`maxVersions` 和 `timeRange` 必須至少設定一個。
limit（可選）	`Integer`	單次最多返回的行數，必須大於 0。達到該值時，可使用響應中的 `nextStartPrimaryKey` 繼續讀取。
columnsToGet（可選）	`Set<String>`	要返回的列名稱。不設定時返回整行；設定後，不返回不包含任何指定列的行。
filter（可選）	`Filter`	過濾條件。同時設定 `columnsToGet` 和 `filter` 時，先篩選返回列，再對結果應用過濾條件。關於過濾條件的配置方法，請參見過濾器。

傳回值

GetRangeResponse 包含以下業務欄位。

欄位	類型	說明
`rows`	`List<Row>`	本次讀取返回的行資料，通過 `getRows` 擷取。
`nextStartPrimaryKey`	`PrimaryKey`	下一次讀取的起始主鍵，通過 `getNextStartPrimaryKey` 擷取。當前範圍已全部讀取時返回 `null`。

情境樣本

分頁迭代讀取

單次響應最多返回 5000 行或 4 MB。響應中的 nextStartPrimaryKey 為下一頁起始主鍵，迴圈調用直至返回 null 即掃完全部資料。

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

int totalRows = 0;
while (true) {
    GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
    totalRows += response.getRows().size();

    // 單次響應未讀完，使用 nextStartPrimaryKey 繼續下一頁
    PrimaryKey nextStart = response.getNextStartPrimaryKey();
    if (nextStart == null) {
        break;
    }
    criteria.setInclusiveStartPrimaryKey(nextStart);
}
System.out.println("Total rows scanned: " + totalRows);

反向讀取

通過 setDirection(Direction.BACKWARD) 反向掃描。反向讀取時起始主鍵必須大於結束主鍵。

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);
criteria.setDirection(Direction.BACKWARD);

// 反向讀取時，起始主鍵必須大於結束主鍵
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (backward): " + response.getRows().size());

條件過濾讀取

通過 setFilter 設定列值過濾條件，僅返回合格行。

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

// 僅返回 col1 等於 "val1" 的行
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
filter.setPassIfMissing(false);
criteria.setFilter(filter);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (filtered): " + response.getRows().size());