行の範囲読み取り - Tablestore SDK for Java - Tablestore - Alibaba Cloud ドキュメントセンター

Tablestore SDK for Java を使用して、プライマリキーの範囲内にあるデータテーブルの連続した行を読み取ります。順方向スキャンと逆方向スキャン、バージョン範囲によるフィルタリング、列値によるフィルタリングをサポートします。

前提条件

getRange を呼び出す前に、Tablestore SDK for Java をインストールし、SyncClient (または AsyncClient) を初期化してください。

機能の説明

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

データテーブルから、プライマリキー範囲内の連続した行をスキャンします。開始と終了のプライマリキーを RangeRowQueryCriteria で指定し、返された行を response.getRows() から取得します。

次の例では、get_range_demo に対して正方向のスキャンを実行し、プライマリキーが row1 以上のすべての行を読み取り、各列の最新バージョンのみを返します。

説明

1 回の範囲スキャンでは、最大 5,000 行または 4 MB が返されます。制限に達すると、レスポンスは nextStartPrimaryKey を次のページの開始プライマリキーに設定します。残りのデータを読み取るには、ループで getRange を呼び出します。

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);
}

パラメータ

クエリ条件を RangeRowQueryCriteria を介して渡します。パラメーターは以下のとおりです。

名前	型	説明
tableName (必須)	String	読み取り元のデータテーブル名。
inclusiveStartPrimaryKey (必須)	PrimaryKey	開始プライマリキー。プライマリキー列の名前と値を指定します。返されるデータには開始プライマリキーが含まれます。プライマリキー列の数と型は、データテーブルのスキーマと一致している必要があります。順方向スキャンの場合、開始プライマリキーは終了プライマリキーより小さくする必要があります。逆方向スキャンの場合、開始プライマリキーは終了プライマリキーより大きくする必要があります。 `PrimaryKeyValue.INF_MIN` は負の無限大を示し、`PrimaryKeyValue.INF_MAX` は正の無限大を示します。
exclusiveEndPrimaryKey (必須)	PrimaryKey	終了プライマリキー。プライマリキー列の名前と値を指定します。返されるデータには終了プライマリキーが含まれません。プライマリキー列の数と型は、データテーブルのスキーマと一致している必要があります。 `PrimaryKeyValue.INF_MIN` は負の無限大を表し、`PrimaryKeyValue.INF_MAX` は正の無限大を表します。
direction (任意)	Direction	スキャンの方向。 `FORWARD` (デフォルト)：順方向スキャン。 `BACKWARD`：逆方向スキャン。
maxVersions (いずれか 1 つ)	OptionalValue<Integer>	バージョンの最大数。`timeRange` が設定されていない場合は必須です。データのバージョン数が `maxVersions` を超える場合、 Tablestore は最新のバージョンを降順で返します。
timeRange (いずれか 1 つ)	OptionalValue<TimeRange>	バージョン範囲であり、 `maxVersions` が設定されていない場合は必須です。属性列には複数のバージョンを格納できます。バージョン範囲を設定すると、Tablestore はその範囲内のバージョンのみを返します。
limit (任意)	int	1 回の呼び出しで返される行数の上限。値は 0 より大きい必要があります。一致するデータが `limit` を超える場合、レスポンスには `limit` 行と、次回の呼び出し用の開始プライマリキーが含まれます。
columnsToGet (任意)	Set<String>	読み取る列。プライマリキー列または属性列を指定できます。 `columnsToGet` が設定されていない場合、`getRange` は行全体を返します。 `columnsToGet` が設定されており、行に指定された列が 1 つも含まれていない場合、その行はレスポンスから除外されます。
filter (任意)	OptionalValue<Filter>	フィルター条件。詳細については、Filter をご参照ください。 `columnsToGet` と `filter` の両方を設定した場合、`getRange` は、最初に `columnsToGet` で列を選択してから、`filter` で行をフィルター処理します。

シナリオ例

ページネーションを使用した反復処理

レスポンス内の nextStartPrimaryKey は、次のページの開始プライマリーキーです。一致するすべての行をスキャンするには、nextStartPrimaryKey が null になるまで getRange をループで呼び出します。

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());

Tablestore:行の範囲読み取り