Table Store SDK は、BatchGetRow、BatchWriteRow、GetRange、createRangeIterator およびその他の行操作 API を提供します。

BatchGetRow

BatchGetRow API は、単一のリクエストで複数の行からデータを読み取ることができます。 パラメーターは GetRow API のものと同じです。 BatchGetRow がすべての行に同じパラメーター条件を使用するように注意します。 たとえば、ColumnsToGet = [colA] の場合、すべての行について colA 値 のみが読み取られます。

BatchGetRow API を使用する場合は、BatchWriteRow API と同様に、戻り値を確認する必要があります。 操作が一部の行で失敗した場合、システムは例外をスローしませんが、失敗した行の情報を BatchGetRowResponse に格納します。 BatchGetRowResponse#getFailedRows メソッドを使用して失敗した行に関する情報を取得するか、BatchGetRowResponse#AllSucceed を使用してすべての行が読み取られたかどうかを判断できます。

BatchGetRow を 10 行読み込むように設定します。 バージョン条件、読み込む列、およびフィルタを設定します。

        private static void batchGetRow(SyncClient client) {
            MultiRowQueryCriteria multiRowQueryCriteria = new MultiRowQueryCriteria(TABLE_NAME);
            // 読み込む行を10行追加します。
            for (int i = 0; i < 10; i++) {
                PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
                primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString("pk" + i));
                PrimaryKey primaryKey = primaryKeyBuilder.build();
                multiRowQueryCriteria.addRow(primaryKey);
            }
            // 条件を追加します。
            multiRowQueryCriteria.setMaxVersions(1);
            multiRowQueryCriteria.addColumnsToGet("Col0");
            multiRowQueryCriteria.addColumnsToGet("Col1");
            SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
                    SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
            singleColumnValueFilter.setPassIfMissing(false);
            multiRowQueryCriteria.setFilter(singleColumnValueFilter);

            BatchGetRowRequest batchGetRowRequest = new BatchGetRowRequest();
            // BatchGetRow を使用すると、複数のテーブルからデータを読み取ることができます。 A single multiRowQueryCriteria corresponds to a query condition for one table. You can add multiRowQueryCriteria.
            batchGetRowRequest.addMultiRowQueryCriteria(multiRowQueryCriteria);

            BatchGetRowResponse batchGetRowResponse = client.batchGetRow(batchGetRowRequest);

            System.out.println("Were all successful:" + batchGetRowResponse.isAllSucceed());
            if (! batchGetRowResponse.isAllSucceed()) {
                for (BatchGetRowResponse.RowResult rowResult : batchGetRowResponse.getFailedRows()) {
                    System.out.println("Failed rows:" + batchGetRowRequest.getPrimaryKey(rowResult.getTableName(), rowResult.getIndex()));
                    System.out.println("Cause of failure:" + rowResult.getError());
                }

                /**
                 * 失敗した行を再試行するための別のリクエストを作成するには、 createRequestForRetry メソッドを使用できます。 ここでは、再試行リクエストの一部のみを構成します。
                 * リトライメソッドには、SDK のカスタムリトライポリシー機能を使用することを推奨します。 この機能を使用すると、バッチ操作後に失敗した行を再試行できます。 再試行ポリシーを設定した後は、呼び出し側の API に再試行コードを追加する必要はありません。
                 */
                BatchGetRowRequest retryRequest = batchGetRowRequest.createRequestForRetry(batchGetRowResponse.getFailedRows());
            }
        }
			

BatchWriteRow

BatchWriteRow API を使用すると、単一の要求で複数の書き込み操作を実行できます。 これらの書き込み操作には、PutRow、UpdateRow および DeleteRowがあります。 この API では、一度に複数のテーブルに書き込むこともできます。

単一の操作を構築するプロセスは、PutRow、UpdateRow または DeleteRow APIを使用するのと同じです。 更新条件を設定することもできます。

BatchWriteRow API を呼び出すときは、必ず戻り値を確認してください。バッチ書き込み中に、他の行が失敗しても、いくつかの行が書き込まれることがあります。 失敗した行インデックスとエラーメッセージは、返された BatchWriteRowResponse に挿入されます。 一部の行が失敗した場合、システムは例外をスローしません。 BatchWriteRowResponse の isAllSucceed メソッドを使用して、すべての行が正常に書き込まれたかどうかを判断できます。 チェックしない場合、失敗した操作の中には無視されるものがあります。 状況によっては、BatchWriteRow API が例外をスローすることがあります。 たとえば、サーバーが、一部の操作に誤ったパラメーターがあることを検出した場合、システムはパラメーターエラー例外をスローすることがあります。 例外がスローされた場合、これは要求内の操作がどれも完了していないことを意味します。

ここでは、単一の BatchWriteRow 要求が送信されます。 2 つの PutRow オペレーション、 1 つの UpdateRow オペレーション、および 1 つの DeleteRow オペレーションが含まれています。

        private static void batchWriteRow(SyncClient client) {
            BatchWriteRowRequest batchWriteRowRequest = new BatchWriteRowRequest();

            // rowPutChange1 を作成します。
            PrimaryKeyBuilder pk1Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            pk1Builder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString("pk1"));
            RowPutChange rowPutChange1 = new RowPutChange(TABLE_NAME, pk1Builder.build());
            // 複数の列を追加します。
            for (int i = 0; i < 10; i++) {
                rowPutChange1.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
            }
             // バッチ操作に追加します。
            batchWriteRowRequest.addRowChange(rowPutChange1);

            // rowPutChange2 を作成します。
            PrimaryKeyBuilder pk2Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            pk2Builder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString("pk2"));
            RowPutChange rowPutChange2 = new RowPutChange(TABLE_NAME, pk2Builder.build());
            // 複数の列を追加します。
            for (int i = 0; i < 10; i++) {
                rowPutChange2.addColumn(new Column("Col" + i, ColumnValue.fromLong(i)));
            }
            // バッチ操作に追加します。
            batchWriteRowRequest.addRowChange(rowPutChange2);

            // rowUpdateChange を作成します。
            PrimaryKeyBuilder pk3Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            pk3Builder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString("pk3"));
            RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, pk3Builder.build());
            // 複数の列を追加します。
            for (int i = 0; i < 10; i++) {
                rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i)));
            }
            // 列を削除します。
            rowUpdateChange.deleteColumns("Col10");
            // バッチ操作に追加します。
            batchWriteRowRequest.addRowChange(rowUpdateChange);

            // rowDeleteChange を作成します。
            PrimaryKeyBuilder pk4Builder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            pk4Builder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString("pk4"));
            RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, pk4Builder.build());
            // バッチ操作に追加します。
            batchWriteRowRequest.addRowChange(rowDeleteChange);

            BatchWriteRowResponse response = client.batchWriteRow(batchWriteRowRequest);

            System.out.println("Were all successful:" + response.isAllSucceed());
            if (! response.isAllSucceed()) {
                for (BatchWriteRowResponse.RowResult rowResult : response.getFailedRows()) {
                    System.out.println("Failed rows:" + batchWriteRowRequest.getRowChange(rowResult.getTableName(), rowResult.getIndex()).getPrimaryKey());
                    System.out.println("Cause of failure:" + rowResult.getError());
                }
                /**
                 * 失敗した行を再試行するための別のリクエストを作成するには、 createRequestForRetry メソッドを使用できます。 ここでは、再試行リクエストの一部のみを構成します。
                 * リトライメソッドは、SDK のカスタムリトライポリシー機能を使用することを推奨します。 この機能を使用すると、バッチ操作後に失敗した行を再試行できます。 再試行ポリシーを設定した後は、呼び出し側の API に再試行コードを追加する必要はありません。
                 */
                BatchWriteRowRequest retryRequest = batchWriteRowRequest.createRequestForRetry(response.getFailedRows());
            }
        }
			

GetRange

GetRange API は、特定の範囲のデータを読み取るために使用されます。 Tabe Store テーブルでは、すべての行はそれらの主キーによってソートされ、プライマリキーはすべてのプライマリキー列によって順番に合成されます。 したがって、行がプライマリキーの特定の列によってソートされると仮定しないでください。

GetRange API を使用すると、特定の範囲に従ってデータを前方または後方に読み取ることができます。 読み取る行数を制限することもできます。 範囲が大きく、スキャンされた行数またはデータ量が制限を超えると、スキャンは停止し、読み取り行と次のプライマリキーが返されます。 すべての行が読み取られない場合は、最後の操作が中断された時点から開始する要求を開始し、前の操作によって戻された次のプライマリキーに基づいて残りの行を読み取ることができます。

GetRange リクエストには、次の主なパラメーターがあります。

  • Direction: 列挙型で、値 FORWARD または BACKWARD を含みます。

  • InclusiveStartPrimaryKey: 開始プライマリキー (包括的) 方向が逆方向に設定されている場合、開始プライマリキーは終了プライマリキーより大きくなければなりません。

  • ExclusiveEndPrimaryKey: 終了プライマリキー(排他的)。 方向が逆方向に設定されている場合、開始プライマリキーは終了プライマリキーより大きくなければなりません。

  • Limit: このリクエストの最大行数。

  • ColumnsToGet: 読み込む列のセット。 これが設定されていない場合は、すべての列が読み取られます。

  • MaxVersions: 読み込むバージョンの最大数。 MaxVersions パラメーターと TimeRange パラメーターの少なくとも一方を設定する必要があります。

  • TimeRange: 読み取るバージョン番号の範囲 MaxVersions パラメーターと TimeRange パラメーターの少なくとも一方を設定する必要があります。

  • Filter: 適用されたフィルター。 サーバーは、読み取り結果を再度フィルター処理するためにフィルターを使用します。

次の操作では、順方向に読み込み、NextStartPrimaryKey が null 値かどうかを判断し、範囲内のすべてのデータを読み込みます。

       private static void getRange(SyncClient client, String startPkValue, String endPkValue) {
            RangeRowQueryCriteria rangeRowQueryCriteria = new RangeRowQueryCriteria(TABLE_NAME);

            // StartPrimaryKey を設定します。
            PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(startPkValue));
            rangeRowQueryCriteria.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());

            // EndPrimaryKey を設定します。
            primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(endPkValue));
            rangeRowQueryCriteria.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());

            rangeRowQueryCriteria.setMaxVersions(1);

            System.out.println("GetRange result:");
            while (true) {
                GetRangeResponse getRangeResponse = client.getRange(new GetRangeRequest(rangeRowQueryCriteria));
                for (Row row : getRangeResponse.getRows()) {
                    System.out.println(row);
                }

                // nextStartPrimaryKey が null 値でない場合は、読み続けます。
                if (getRangeResponse.getNextStartPrimaryKey() ! = null) {
                    rangeRowQueryCriteria.setInclusiveStartPrimaryKey(getRangeResponse.getNextStartPrimaryKey());
                } else {
                    break;
                }
            }
        }
			

createRangeIterator

次の操作はデータを繰り返し読み込みます。

        private static void getRangeByIterator(SyncClient client, String startPkValue, String endPkValue) {
            RangeIteratorParameter rangeIteratorParameter = new RangeIteratorParameter(TABLE_NAME);

            // StartPrimaryKey を設定します。
            PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(startPkValue));
            rangeIteratorParameter.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());

            // EndPrimaryKey を設定します。
            primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(endPkValue));
            rangeIteratorParameter.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());

            rangeIteratorParameter.setMaxVersions(1);

            Iterator<Row> iterator = client.createRangeIterator(rangeIteratorParameter);

            System.out.println("Use Iterator to implement GetRange result:");
            while (iterator.hasNext()) {
                Row row = iterator.next();
                System.out.println(row);
            }
        }