セカンダリインデックスからのデータ読み取り - Tablestore SDK for Java - Tablestore

Tablestore SDK for Java を使用して、グローバルセカンダリインデックスまたはローカルセカンダリインデックスからデータを読み取ります。

前提条件

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

機能の説明

セカンダリインデックスは、データテーブルのプライマリキー列と事前定義列を再配置して、代替の読み取りパスを提供します。インデックステーブルは読み取り専用です。インデックステーブルには、インデックスプライマリキー、Tablestore によってデータテーブルから自動的に追加されるプライマリキー列、およびインデックス作成時に指定された属性列が含まれます。インデックステーブルに含まれていない属性列を取得するには、返されたデータテーブルのプライマリキーを使用してデータテーブルをクエリします。詳細については、「セカンダリインデックス」をご参照ください。

インデックステーブルを読み取る際、プライマリキー列の名前と順序は、インデックステーブルのプライマリキースキーマと一致する必要があります。たとえば、データテーブルがプライマリキーとして user_id と order_id を使用し、category がインデックス列として追加されると仮定します。次の表は、グローバルセカンダリインデックスとローカルセカンダリインデックスの完全なプライマリキーの順序を比較したものです。

インデックスタイプ	インデックス作成時に指定されたインデックスプライマリキー	インデックステーブルの完全なプライマリキーの順序
グローバルセカンダリインデックス	`category`	`category`、`user_id`、`order_id`。 Tablestore は、指定されていないデータテーブルのプライマリキー列をインデックスプライマリキーに追加します。
ローカルセカンダリインデックス	`user_id` および `category`	`user_id`、`category`、`order_id`。最初のインデックスプライマリキー列は、データテーブルの最初のプライマリキー列と同じである必要があります。

重要

既存のデータを含めてグローバルセカンダリインデックスを作成する場合、既存のデータが構築および同期されるまでインデックステーブルを読み取ることはできません。同期が完了するまで待ってから、インデックステーブルを読み取ってください。

getRow を呼び出して、インデックステーブルの完全なプライマリキーを使用して行を読み取ります。

public GetRowResponse getRow(GetRowRequest getRowRequest)
        throws TableStoreException, ClientException

getRange を呼び出して、インデックステーブルのプライマリーキーの範囲内のデータを読み取ります。

public GetRangeResponse getRange(GetRangeRequest getRangeRequest)
        throws TableStoreException, ClientException

次の例では、完全なプライマリキーを使用して、example_global_index グローバルセカンダリインデックスから 1 行を読み取り、status 属性列のみを返します。

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user-1"))
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.fromLong(101L))
        .build();

SingleRowQueryCriteria criteria =
        new SingleRowQueryCriteria("example_global_index", primaryKey);
criteria.addColumnsToGet("status");
criteria.setMaxVersions(1);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println(response.getRow());

パラメーター

単一行読み取りのパラメーター

GetRowRequest には、以下のパラメーターが含まれます。

名前	タイプ	説明
rowQueryCriteria (必須)	`SingleRowQueryCriteria`	単一行を読み取るための条件です。

単一行読み取り条件

rowQueryCriteria は SingleRowQueryCriteria 型で、以下のパラメーターを含みます。

名前	タイプ	説明
tableName (必須)	`String`	インデックステーブルの名前です。
primaryKey (必須)	`PrimaryKey`	インデックステーブル内の行の完全なプライマリキーです。プライマリキーには、インデックス作成時に指定されたインデックスプライマリキー列と、Tablestore によって自動的に追加されたデータテーブルのプライマリキー列が含まれている必要があります。列の名前と順序は、インデックステーブルのスキーマと一致する必要があります。
columnsToGet (任意)	`Set<String>`	返す属性列の名前です。最大 128 列まで指定できます。このパラメーターが指定されていない場合、インデックステーブル内の行のすべての属性列が返されます。インデックステーブルに含まれていない属性列は返されず、データテーブルから取得する必要があります。
maxVersions (条件付き必須)	`int`	各属性列に対して返されるバージョンの最大数。値は 0 より大きくする必要があります。セカンダリインデックスは最新バージョンのみを保持します。ほとんどの場合、このパラメーターを `1` に設定します。`maxVersions` と `timeRange` のいずれか一方のみを指定します。
timeRange (条件付き必須)	`TimeRange`	属性列バージョンのタイムスタンプ範囲 (ミリ秒単位)。範囲は左閉右開です。`timeRange` または `maxVersions` のいずれかを指定しますが、両方を指定することはできません。
filter (任意)	`Filter`	サーバー側フィルターです。行がフィルター条件を満たさない場合、その行は返されません。
startColumn (任意)	`String`	辞書順で返す最初の属性列の名前です。指定された列は含まれます。このパラメーターは、ワイド行の読み取りを目的としています。
endColumn (任意)	`String`	辞書順で返す最後の属性列の名前です。指定された列は除外されます。このパラメーターは、ワイド行の読み取りを目的としています。

複数行範囲読み取りのパラメーター

GetRangeRequest には、次のパラメーターが含まれています。

名前	タイプ	説明
rangeRowQueryCriteria (必須)	`RangeRowQueryCriteria`	複数行の範囲を読み取るための条件です。

範囲読み取り条件

rangeRowQueryCriteria は RangeRowQueryCriteria 型で、次のパラメーターを含みます。

名前	タイプ	説明
tableName (必須)	`String`	インデックステーブルの名前です。
inclusiveStartPrimaryKey (必須)	`PrimaryKey`	範囲の開始プライマリキー。プライマリキーは結果に含まれ、インデックステーブルのすべてのプライマリキー列を含む必要があります。プライマリキー列の最小値と最大値を表すには、`INF_MIN` と `INF_MAX` を使用できます。
exclusiveEndPrimaryKey (必須)	`PrimaryKey`	範囲の終了プライマリキーです。このプライマリキーは結果から除外され、インデックステーブルのすべてのプライマリキー列を含む必要があります。プライマリキー列の最小値と最大値を表すには、`INF_MIN` および `INF_MAX` を使用できます。
direction (任意)	`Direction`	読み取り方向。有効な値は `FORWARD` と `BACKWARD` です。デフォルト値: `FORWARD`。順方向の読み取りの場合、開始プライマリキーは終了プライマリキーより小さい必要があります。逆方向の読み取りの場合、開始プライマリキーは終了プライマリキーより大きい必要があります。
limit (任意)	`int`	1 回のリクエストで返す行の最大数。値は 0 より大きい必要があります。デフォルト値は `-1` で、クライアントが返される行数を制限しないことを意味します。サーバーは、1 回のレスポンスで最大 5,000 行と 4 MB のデータを返します。
columnsToGet (任意)	`Set<String>`	返す属性列の名前です。最大 128 列まで指定できます。このパラメーターが指定されていない場合、インデックステーブル内の各行のすべての属性列が返されます。指定された属性列のいずれも行に存在しない場合、その行は返されません。データテーブルをクエリする前に、インデックステーブルに存在する列を読み取るか、このパラメーターを未指定にしてください。
maxVersions (条件付き必須)	`int`	各属性列で返すバージョンの最大数です。値は 0 より大きい必要があります。セカンダリインデックスは最新バージョンのみを保持します。ほとんどの場合、このパラメーターを `1` に設定します。`maxVersions` または `timeRange` のいずれかを指定します。両方を同時に指定することはできません。
timeRange (条件付き必須)	`TimeRange`	属性列バージョンのタイムスタンプ範囲 (ミリ秒) です。範囲は左閉右開です。`timeRange` または `maxVersions` のいずれかを指定しますが、両方を指定することはできません。
filter (任意)	`Filter`	サーバー側フィルターです。フィルター条件を満たす行のみが返されます。
startColumn (任意)	`String`	辞書順で返す最初の属性列の名前です。指定された列は含まれます。このパラメーターは、ワイド行の読み取りを目的としています。
endColumn (任意)	`String`	辞書順で返す最後の属性列の名前です。指定された列は除外されます。このパラメーターは、ワイド行の読み取りを目的としています。

戻り値

単一行読み取りの戻り値

GetRowResponse には、以下のレスポンスパラメーターが含まれています。

名前	タイプ	説明
row	`Row`	返される行。行が存在しない場合は、`null` が返されます。
consumedCapacity	`ConsumedCapacity`	この操作の消費キャパシティです。

複数行範囲読み取りの戻り値

GetRangeResponse には、以下のレスポンスパラメーターが含まれます。

名前	タイプ	説明
rows	`List<Row>`	リクエストによって返された行です。
nextStartPrimaryKey	`PrimaryKey`	次のリクエストの開始プライマリーキーです。このパラメーターが `null` でない場合は、次のリクエストで `inclusiveStartPrimaryKey` として使用してください。このパラメーターが `null` の場合、指定された範囲内のすべての行が読み取られたことを意味します。このパラメーターは、`limit` が指定されていなくても、レスポンスがサーバーの制限に達したときに返される場合があります。
consumedCapacity	`ConsumedCapacity`	この操作の消費キャパシティです。

シナリオ

グローバルセカンダリインデックスからの複数行範囲読み取り

次の例では、example_global_index グローバルセカンダリインデックスから category の値が books である行を読み取り、nextStartPrimaryKey ページネーショントークンを処理します。

PrimaryKey startPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MIN)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MIN)
        .build();
PrimaryKey endPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MAX)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MAX)
        .build();

RangeRowQueryCriteria rangeCriteria =
        new RangeRowQueryCriteria("example_global_index");
rangeCriteria.setInclusiveStartPrimaryKey(startPrimaryKey);
rangeCriteria.setExclusiveEndPrimaryKey(endPrimaryKey);
rangeCriteria.setMaxVersions(1);
rangeCriteria.setLimit(100);

List<Row> rows = new ArrayList<>();
while (true) {
    GetRangeResponse response =
            client.getRange(new GetRangeRequest(rangeCriteria));
    rows.addAll(response.getRows());

    if (response.getNextStartPrimaryKey() == null) {
        break;
    }
    rangeCriteria.setInclusiveStartPrimaryKey(
            response.getNextStartPrimaryKey());
}
rows.forEach(System.out::println);

データテーブルに対する属性列のクエリ

次の例では、前の例で返された rows を使用して、各インデックステーブルの主キーからデータテーブルの主キーを抽出し、インデックステーブルに含まれていない detail 属性列を example_table データテーブルからクエリします。

for (Row indexRow : rows) {
    PrimaryKey indexPrimaryKey = indexRow.getPrimaryKey();
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn(
                    "user_id",
                    indexPrimaryKey.getPrimaryKeyColumn("user_id").getValue())
            .addPrimaryKeyColumn(
                    "order_id",
                    indexPrimaryKey.getPrimaryKeyColumn("order_id").getValue())
            .build();

    SingleRowQueryCriteria rowCriteria =
            new SingleRowQueryCriteria("example_table", primaryKey);
    rowCriteria.addColumnsToGet("detail");
    rowCriteria.setMaxVersions(1);

    GetRowResponse response =
            client.getRow(new GetRowRequest(rowCriteria));
    System.out.println(response.getRow());
}