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

前提条件

Tablestore SDK for Java をインストールし、クライアントを初期化します。

説明

getRange を呼び出して、プライマリキーの範囲内にある連続した行を正方向または逆方向で読み取ります。取得する列、データバージョンの範囲、フィルター条件を指定できます。

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

説明

1回の範囲読み取りでは、最大 5,000 行または 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`	各属性列に対して返すデータバージョンの最大数。一致するバージョンがさらにある場合、Tablestore は新しいバージョンから順に返します。`maxVersions` と `timeRange` のうち、少なくとも 1 つを設定する必要があります。
timeRange (任意)	`TimeRange`	データバージョンの範囲。範囲内のバージョンのみが返されます。`maxVersions` と `timeRange` のうち、少なくとも 1 つを設定する必要があります。
limit (任意)	`Integer`	1 回の呼び出しで返す行の最大数。値は 0 より大きい必要があります。上限に達した場合は、レスポンスの `nextStartPrimaryKey` を使用して読み取りを続行します。
columnsToGet (任意)	`Set<String>`	返す列。このパラメーターを指定しない場合、行全体が返されます。指定した場合、指定された列を 1 つも含まない行は返されません。
filter (任意)	`Filter`	フィルター条件。`columnsToGet` と `filter` の両方を指定した場合、Tablestore は最初に取得する列を選択し、次にフィルターを適用します。フィルターの設定方法の詳細については、「フィルターの使用」をご参照ください。

レスポンス

GetRangeResponse には、この操作に固有の以下のフィールドが含まれています。

フィールド	型	説明
`rows`	`List<Row>`	現在の呼び出しで返された行。`getRows` を呼び出して取得します。
`nextStartPrimaryKey`	`PrimaryKey`	次回呼び出し用の開始プライマリキー。`getNextStartPrimaryKey` を呼び出して取得します。範囲の読み取りが完了した場合、`null` が返されます。

シナリオ例

ページネーションによる反復

レスポンスの 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("スキャンされた合計行数: " + 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("行 (逆方向): " + 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("行 (フィルター適用後): " + response.getRows().size());