イテレーターを使用した行の読み取り - Tablestore SDK for Java - Tablestore

前提条件

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

説明

createRangeIterator メソッドを呼び出して、指定したプライマリキー範囲の行イテレーターを作成します。現在のバッチを読み切ると、イテレーターは次のリクエストを自動的に発行します。nextStartPrimaryKey を追跡したり、getRange をループしたりする必要はありません。

public Iterator<Row> createRangeIterator(RangeIteratorParameter rangeIteratorParameter) throws TableStoreException, ClientException

次の例では、range_iter_demo テーブルを順方向に反復処理します。プライマリキー row1 から開始し、テーブルの末尾まで続けて各行を出力します。

String tableName = "range_iter_demo";
RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

// 開始プライマリキー (含む)
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
parameter.setInclusiveStartPrimaryKey(startPkBuilder.build());

// 終了プライマリキー (含まない)。 INF_MAX を指定するとテーブルの末尾まで読み取ります。
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setExclusiveEndPrimaryKey(endPkBuilder.build());

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
int count = 0;
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
    count++;
}
System.out.println("Total rows iterated: " + count);

パラメーター

RangeIteratorParameter を使用して反復処理のクエリ条件を指定します。パラメーターを次に示します。

名前	タイプ	説明
tableName (必須)	String	読み取るテーブルの名前。
inclusiveStartPrimaryKey (必須)	PrimaryKey	開始プライマリキー。プライマリキー列名と値を含みます。返されるデータには開始プライマリキーが含まれます。プライマリキー列の数と型は、テーブルスキーマと一致している必要があります。順方向の反復処理の場合、開始プライマリキーは終了プライマリキーより小さい必要があります。逆方向の反復処理の場合、開始プライマリキーは終了プライマリキーより大きい必要があります。負の無限大には `PrimaryKeyValue.INF_MIN` を、正の無限大には `PrimaryKeyValue.INF_MAX` を使用します。
exclusiveEndPrimaryKey (必須)	PrimaryKey	終了プライマリキー。プライマリキー列名と値を含みます。返されるデータには終了プライマリキーが含まれません。プライマリキー列の数と型は、テーブルスキーマと一致している必要があります。負の無限大には `PrimaryKeyValue.INF_MIN` を、正の無限大には `PrimaryKeyValue.INF_MAX` を使用します。
direction (オプション)	Direction	読み取り方向。 `FORWARD`：デフォルト。順方向に反復処理します。 `BACKWARD`：逆方向に反復処理します。
maxVersions (オプション)	OptionalValue<Integer>	属性列ごとに返されるバージョンの最大数。`maxVersions` と `timeRange` の少なくとも一方を設定する必要があります。一致するバージョンがこの最大数を超える場合、Tablestore は新しいものから古いものの順に、この最大数までバージョンを返します。
timeRange (オプション)	OptionalValue<TimeRange>	バージョン範囲。`maxVersions` と `timeRange` の少なくとも一方を設定する必要があります。各属性列は複数バージョンを保持できます。バージョン範囲を設定すると、その範囲内のデータのみが返されます。
maxCount (オプション)	int	イテレーターが返す行の総数の上限。0 より大きい値にする必要があります。
bufferSize (オプション)	int	内部リクエストごとに取得する行数。0 より大きい値にする必要があります。大規模スキャン時のピークメモリ使用量を削減するには、この値を小さくします。現在のバッチを読み切ると、イテレーターは中断した位置から次のバッチを自動的にリクエストします。
columnsToGet (オプション)	Set<String>	読み取る列。プライマリキー列、または属性列を指定できます。 `columnsToGet` を設定しない場合、行全体が返されます。 `columnsToGet` を設定し、行に指定した列が 1 つも含まれない場合は、属性列が空の `Row` オブジェクトが返されます。
filter (オプション)	OptionalValue<Filter>	フィルター条件。詳細については、「Use filters」をご参照ください。 `columnsToGet` と `filter` の両方を設定した場合、まず `columnsToGet` が列を選択し、その後 `filter` が行を評価します。

レスポンス

createRangeIterator は Iterator<Row> を返します。hasNext() を呼び出して追加データの有無を確認し、next() を呼び出して次の Row オブジェクトを取得します。

例

逆方向の反復処理

setDirection(Direction.BACKWARD) を使用して逆方向に反復処理します。逆方向の反復処理では、開始プライマリキーが終了プライマリキーより 大きい 必要があります。

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);
parameter.setDirection(Direction.BACKWARD);

// 逆方向の反復処理では、開始プライマリキーが終了プライマリキーより大きい必要があります。
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setInclusiveStartPrimaryKey(startPkBuilder.build());

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

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

行の総数の制限

setMaxCount を使用して、イテレーターが返す行の総数に上限を設定します。これは Top-N 読み取りに有用で、不要なスキャンを回避できます。

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// 最大 3 行を返します。
parameter.setMaxCount(3);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

バッチサイズによるメモリの最適化

setBufferSize を使用して、内部リクエストごとに取得する行数を制御します。大規模スキャン時のピークメモリ使用量を削減するには、この値を小さくします。

String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// 内部リクエストごとに 2 行を取得します。
parameter.setBufferSize(2);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}