範圍讀取資料

Java SDK 按主鍵範圍讀取資料表中的連續多行資料，支援正反向讀取、按版本範圍過濾、按列值過濾，適用於按主鍵區間批量掃描行資料的情境。

前提條件

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

功能說明

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

按主鍵範圍掃描資料表中的連續多行。通過 RangeRowQueryCriteria 指定起始和結束主鍵，結果通過 response.getRows() 擷取行列表。

以下樣本從資料表 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));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Read CU: " + response.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
for (Row row : response.getRows()) {
    System.out.println(row);
}

說明

單次範圍掃描資料上限為 5000 行或者 4 MB。超出限制時，響應中的 nextStartPrimaryKey 返回下一頁起始主鍵，需迴圈調用讀取剩餘資料。

關鍵參數：

tableName（必選）：讀取的資料表名稱。
inclusiveStartPrimaryKey（必選）：起始主鍵，包含該主鍵。
exclusiveEndPrimaryKey（必選）：結束主鍵，不包含該主鍵。
maxVersions 或 timeRange（二選一）：最大版本數或資料版本範圍。

參數說明

通過 RangeRowQueryCriteria 攜帶查詢條件，各參數說明如下。

名稱	類型	說明
tableName（必選）	String	讀取的資料表名稱。
inclusiveStartPrimaryKey（必選）	PrimaryKey	起始主鍵資訊，包括主鍵列名稱和主索引值。返回資料包含起始主鍵。主鍵個數和類型必須與資料表的主鍵 schema 保持一致。正向讀取時，起始主鍵必須小於結束主鍵。反向讀取時，起始主鍵必須大於結束主鍵。 `PrimaryKeyValue.INF_MIN` 表示無限小，`PrimaryKeyValue.INF_MAX` 表示無限大。
exclusiveEndPrimaryKey（必選）	PrimaryKey	結束主鍵資訊，包括主鍵列名稱和主索引值。返回資料不包含結束主鍵。主鍵個數和類型必須與資料表的主鍵 schema 保持一致。 `PrimaryKeyValue.INF_MIN` 表示無限小，`PrimaryKeyValue.INF_MAX` 表示無限大。
direction（可選）	Direction	讀取方向。 `FORWARD`：預設值，正向讀取。 `BACKWARD`：反向讀取。
maxVersions（二選一）	OptionalValue<Integer>	最大版本數。`maxVersions` 和 `timeRange` 必須至少設定一個。如果符合查詢條件的資料版本數量超過設定的最大版本數，按從新到舊的順序返回指定版本數量的資料。
timeRange（二選一）	OptionalValue<TimeRange>	資料版本範圍。`maxVersions` 和 `timeRange` 必須至少設定一個。資料表的每個屬性列可以有不同的資料版本，設定版本範圍後僅返回該範圍內的資料。
limit（可選）	int	單次返回最大行數，必須大於 0。如果符合查詢條件的資料行數大於設定的值，返回指定的最大行數和用於下一次查詢的起始主索引值。
columnsToGet（可選）	Set<String>	指定讀取的資料列，可以是主鍵列或屬性列。不設定 `columnsToGet` 時，返回整行資料。設定後如果讀取的行資料不包含任何指定的資料列，不返回該行資料。
filter（可選）	OptionalValue<Filter>	過濾條件，詳情請參見過濾器。如果同時設定 `columnsToGet` 和 `filter`，先按 `columnsToGet` 篩選資料列，再按 `filter` 條件過濾資料。

情境樣本

分頁迭代讀取

單次響應最多返回 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());