Java で Cloud Spanner を使ってみる

目標

このチュートリアルでは、Java 用の Cloud Spanner クライアント ライブラリを使用するステップを詳しく説明します。

  • Cloud Spanner のインスタンスとデータベースを作成します。
  • データベースのデータに対し、書き込み、読み取り、SQL クエリの実行を行います。
  • データベース スキーマを更新します。
  • 読み取り / 書き込みトランザクションを使用してデータを更新します。
  • セカンダリ インデックスをデータベースに追加します。
  • インデックスを使用して、データの読み込みと SQL クエリの実行を行います。
  • 読み取り専用トランザクションを使用してデータを取得します。

料金

このチュートリアルで使用する Cloud Spanner は、Google Cloud Platform の有料コンポーネントです。Cloud Spanner を使用する料金については、料金をご覧ください。

始める前に

  1. 設定に示されている手順を完了します。その手順では、Google Cloud Platform のデフォルト プロジェクトの作成と設定、課金の有効化、Cloud Spanner API の有効化、Cloud Spanner API を使用するのに必要な認証情報を取得するために OAuth 2.0 を設定する方法について説明しています。
    特に、ローカル開発環境で認証情報を設定するために、必ず gcloud auth application-default login を実行してください。

  2. 開発マシンに次のものがまだインストールされていない場合はインストールします。

  3. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
    

    あるいは、zip 形式のサンプルをダウンロードして、ファイルを抽出することもできます。

  4. Cloud Spanner のサンプルコードが含まれるディレクトリに移動します。

    cd java-docs-samples/spanner/cloud-client
    

インスタンスの作成

Cloud Spanner を最初に使用するときは、インスタンスを作成する必要があります。インスタンスとは、Cloud Spanner データベースによって使用されるリソースの割り当てのことです。インスタンスを作成するときは、インスタンス構成を選択してデータの格納場所を指定し、さらに使用するノード数も選択して、インスタンスの配信リソースおよびストレージ リソースの量を決定します。

次のコマンドを実行して、1 ノードの us-central1 リージョンに Cloud Spanner インスタンスを作成します。

gcloud spanner instances create test-instance --config=regional-us-central1 \
  --description="Test Instance" --nodes=1

これにより、次の特性を持つインスタンスが作成されます。

  • インスタンス ID test-instance
  • 表示名 Test Instance
  • インスタンス構成 regional-us-central1(リージョン構成ではデータが単一のリージョンに保存され、マルチリージョン構成ではデータが複数のリージョンに分散されます。詳しくは、インスタンスをご覧ください。)
  • ノード数 1(node_count はインスタンスのデータベースで使用可能な配信リソースとストレージ リソースの量に対応します。詳しくは、ノード数をご覧ください。)

以下のように表示されます。

Creating instance...done.

サンプル ファイルの確認

サンプル リポジトリには、Cloud Spanner を Java で使用する方法を示すサンプルが含まれます。

pom.xml は、Java 用 Cloud Spanner クライアント ライブラリをプロジェクトの依存関係に追加し、このチュートリアルで定義される Java クラスを含む実行可能 JAR ファイルをビルドするためのアセンブリ プラグインを構成します。

spanner/cloud-client ディレクトリからサンプルをビルドします。

mvn package

データベースの作成

コマンドラインで次のコマンドを実行して、test-instance というインスタンスに example-db というデータベースを作成します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
createdatabase test-instance example-db

以下のように表示されます。

Created database [example-db]

これで Cloud Spanner データベースが作成されました。データベースを作成したコードは次のとおりです。

static void createDatabase(DatabaseAdminClient dbAdminClient, DatabaseId id) {
  OperationFuture<Database, CreateDatabaseMetadata> op =
      dbAdminClient.createDatabase(
          id.getInstanceId().getInstance(),
          id.getDatabase(),
          Arrays.asList(
              "CREATE TABLE Singers (\n"
                  + "  SingerId   INT64 NOT NULL,\n"
                  + "  FirstName  STRING(1024),\n"
                  + "  LastName   STRING(1024),\n"
                  + "  SingerInfo BYTES(MAX)\n"
                  + ") PRIMARY KEY (SingerId)",
              "CREATE TABLE Albums (\n"
                  + "  SingerId     INT64 NOT NULL,\n"
                  + "  AlbumId      INT64 NOT NULL,\n"
                  + "  AlbumTitle   STRING(MAX)\n"
                  + ") PRIMARY KEY (SingerId, AlbumId),\n"
                  + "  INTERLEAVE IN PARENT Singers ON DELETE CASCADE"));
  try {
    // Initiate the request which returns an OperationFuture.
    Database db = op.get();
    System.out.println("Created database [" + db.getId() + "]");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

コードでは、基本的な音楽アプリケーション用の 2 つのテーブル SingersAlbums も定義されています。これらのテーブルはこのページ全体で使用されています。まだスキーマ例を見ていない場合は確認してください。

次のステップでは、データベースにデータを書き込みます。

データベース クライアントの作成

読み取りまたは書き込みを行うには、まず DatabaseClient を作成する必要があります。DatabaseClient はデータベース接続と考えることができます。Cloud Spanner とのすべてのやりとりは DatabaseClient 経由で実行されます。通常はアプリケーション開始時に DatabaseClient が作成され、読み取りや書き込み、トランザクションの実行に DatabaseClient が再利用されます。

SpannerOptions options = SpannerOptions.newBuilder().build();
Spanner spanner = options.getService();
try {
  String command = args[0];
  DatabaseId db = DatabaseId.of(options.getProjectId(), args[1], args[2]);
  DatabaseClient dbClient = spanner.getDatabaseClient(db);
  DatabaseAdminClient dbAdminClient = spanner.getDatabaseAdminClient();

クライアントごとに Cloud Spanner のリソースを使用するため、close() を呼び出して不要なクライアントを閉じることをおすすめします。

詳細については、DatabaseClient Javadoc リファレンスをご覧ください。

DML でのデータの書き込み

読み取り / 書き込みトランザクションでデータ操作言語(DML)を使用してデータを挿入できます。

executeUpdate() メソッドを使用して DML ステートメントを実行します。

static void writeUsingDml(DatabaseClient dbClient) {
  // Insert 4 singer records
  dbClient
      .readWriteTransaction()
      .run(
          new TransactionCallable<Void>() {
            @Override
            public Void run(TransactionContext transaction) throws Exception {
              String sql =
                  "INSERT INTO Singers (SingerId, FirstName, LastName) VALUES "
                      + "(12, 'Melissa', 'Garcia'), "
                      + "(13, 'Russell', 'Morales'), "
                      + "(14, 'Jacqueline', 'Long'), "
                      + "(15, 'Dylan', 'Shaw')";
              long rowCount = transaction.executeUpdate(Statement.of(sql));
              System.out.printf("%d records inserted.\n", rowCount);
              return null;
            }
          });
}

writeusingdml 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
writeusingdml test-instance example-db

以下のように表示されます。

4 records inserted.

ミューテーションでのデータの書き込み

ミューテーションを使ってデータを挿入することもできます。

データの書き込みには Mutation オブジェクトを使用します。Mutation オブジェクトは、ミューテーション オペレーションのためのコンテナです。Mutation は挿入、更新、削除など、Cloud Spanner データベース内のさまざまな行やテーブルに、Cloud Spanner によってアトミックに適用される一連の操作を表します。

Mutation クラスの newInsertBuilder() メソッドは、テーブルに新しい行を挿入する INSERT ミューテーションを作成します。行がすでに存在する場合、書き込みは失敗します。または、newInsertOrUpdateBuilder メソッドを使用して INSERT_OR_UPDATE ミューテーションを構成できます。これにより、行がすでに存在している場合に列値が更新されます。

DatabaseClient クラスの write() メソッドでミューテーションを書き込みます。1 つのバッチ内のすべてのミューテーションはアトミックに適用されます。

次のコードは、ミューテーションを使用してデータを書き込む方法を示しています。

static final List<Singer> SINGERS =
    Arrays.asList(
        new Singer(1, "Marc", "Richards"),
        new Singer(2, "Catalina", "Smith"),
        new Singer(3, "Alice", "Trentor"),
        new Singer(4, "Lea", "Martin"),
        new Singer(5, "David", "Lomond"));

static final List<Album> ALBUMS =
    Arrays.asList(
        new Album(1, 1, "Total Junk"),
        new Album(1, 2, "Go, Go, Go"),
        new Album(2, 1, "Green"),
        new Album(2, 2, "Forever Hold Your Peace"),
        new Album(2, 3, "Terrified"));
static void writeExampleData(DatabaseClient dbClient) {
  List<Mutation> mutations = new ArrayList<>();
  for (Singer singer : SINGERS) {
    mutations.add(
        Mutation.newInsertBuilder("Singers")
            .set("SingerId")
            .to(singer.singerId)
            .set("FirstName")
            .to(singer.firstName)
            .set("LastName")
            .to(singer.lastName)
            .build());
  }
  for (Album album : ALBUMS) {
    mutations.add(
        Mutation.newInsertBuilder("Albums")
            .set("SingerId")
            .to(album.singerId)
            .set("AlbumId")
            .to(album.albumId)
            .set("AlbumTitle")
            .to(album.albumTitle)
            .build());
  }
  dbClient.write(mutations);
}

write 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
write test-instance example-db

コマンドが正常に実行されることを確認してください。

SQL を使用したデータのクエリ

Cloud Spanner は、データを読み取るためにネイティブ SQL インターフェースをサポートします。これにアクセスするには、コマンドラインで gcloud コマンドライン ツールを使用するか、プログラミングによって Java 用 Cloud Spanner クライアント ライブラリを使用します。

コマンドラインから

Albums テーブルのすべての列から値を読み取るには、次の SQL ステートメントを実行します。

gcloud spanner databases execute-sql example-db --instance=test-instance --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

結果は次のようになります。

SingerId AlbumId AlbumTitle
1        1       Total Junk
1        2       Go, Go, Go
2        1       Green
2        2       Forever Hold Your Peace
2        3       Terrified

Java 用の Cloud Spanner クライアント ライブラリの使用

コマンドラインで SQL ステートメントを実行するだけでなく、Java 用の Cloud Spanner クライアント ライブラリを使用して同じ SQL ステートメントをプログラマティックに発行できます。

SQL クエリの実行には次のメソッドとクラスが使用されます。

  • DatabaseClient クラスの singleUse() メソッド: これを使用して、Cloud Spanner テーブルの 1 つ以上の行から 1 つ以上の列の値を読み取ります。singleUse() は、読み取りまたは SQL ステートメントを実行するために使用される ReadContext オブジェクトを返します。
  • ReadContext クラスの executeQuery() メソッド: データベースに対してクエリを実行するには、このメソッドを使用します。
  • Statement クラス: SQL 文字列を作成するときに使用します。
  • ResultSet クラス: これを使用して、SQL ステートメントまたは読み取り呼び出しから返されたデータにアクセスします。

クエリを発行してデータにアクセスする方法を次に示します。

static void query(DatabaseClient dbClient) {
  // singleUse() can be used to execute a single read or query against Cloud Spanner.
  ResultSet resultSet =
      dbClient
          .singleUse()
          .executeQuery(Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"));
  while (resultSet.next()) {
    System.out.printf(
        "%d %d %s\n", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
  }
}

query 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
query test-instance example-db

次のような結果が表示されます。

1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified

読み取り API を使用したデータの読み込み

Cloud Spanner の SQL インターフェースに加えて、Cloud Spanner は読み取りインターフェースもサポートしています。

データベースから行を読み取るには、ReadContext クラスの read() メソッドを使用します。読み取るキーとキー範囲のコレクションを定義するには、KeySet オブジェクトを使用します。

データを読み取る方法を次に示します。

static void read(DatabaseClient dbClient) {
  ResultSet resultSet =
      dbClient
          .singleUse()
          .read(
              "Albums",
              // KeySet.all() can be used to read all rows in a table. KeySet exposes other
              // methods to read only a subset of the table.
              KeySet.all(),
              Arrays.asList("SingerId", "AlbumId", "AlbumTitle"));
  while (resultSet.next()) {
    System.out.printf(
        "%d %d %s\n", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
  }
}

read 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
read test-instance example-db

次のような出力が表示されます。

1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified

データベース スキーマの更新

MarketingBudget という列を新たに Albums テーブルに追加する必要があるとします。既存のテーブルに新しい列を追加するには、データベース スキーマの更新が必要です。Cloud Spanner は、トラフィック提供中のデータベースへのスキーマの更新をサポートしています。スキーマの更新では、データベースをオフラインにする必要がなく、テーブル全体や列がロックされないため、スキーマの更新中もデータベースへのデータの書き込みを続けることができます。サポートされるスキーマの更新とスキーマ変更のパフォーマンスの詳細については、スキーマの更新をご覧ください。

列の追加

列を追加するには、コマンドラインで gcloud コマンドライン ツールを使用するか、Java 用 Cloud Spanner クライアント ライブラリを使用してプログラムによって行います。

コマンドラインから

テーブルに新しい列を追加するには、次の ALTER TABLE コマンドを使用します。

gcloud spanner databases ddl update example-db --instance=test-instance \
  --ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'

以下のように表示されます。

DDL updating...done.

Java 用の Cloud Spanner クライアント ライブラリの使用

DatabaseAdminClient クラスの updateDatabaseDdl() メソッドを使用してスキーマを変更します。

static void addMarketingBudget(DatabaseAdminClient adminClient, DatabaseId dbId) {
  OperationFuture<Void, UpdateDatabaseDdlMetadata> op =
      adminClient
        .updateDatabaseDdl(
            dbId.getInstanceId().getInstance(),
            dbId.getDatabase(),
            Arrays.asList("ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"),
            null);
  try {
    // Initiate the request which returns an OperationFuture.
    op.get();
    System.out.println("Added MarketingBudget column");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

addmarketingbudget 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
addmarketingbudget test-instance example-db

以下のように表示されます。

Added MarketingBudget column.

新しい列へのデータの書き込み

次のコードは、新しい列にデータを書き込みます。MarketingBudget の値を、キーが Albums(1, 1) の行では 100000 に、キーが Albums(2, 2) の行では 500000 に設定します。

static void update(DatabaseClient dbClient) {
  // Mutation can be used to update/insert/delete a single row in a table. Here we use
  // newUpdateBuilder to create update mutations.
  List<Mutation> mutations =
      Arrays.asList(
          Mutation.newUpdateBuilder("Albums")
              .set("SingerId")
              .to(1)
              .set("AlbumId")
              .to(1)
              .set("MarketingBudget")
              .to(100000)
              .build(),
          Mutation.newUpdateBuilder("Albums")
              .set("SingerId")
              .to(2)
              .set("AlbumId")
              .to(2)
              .set("MarketingBudget")
              .to(500000)
              .build());
  // This writes all the mutations to Cloud Spanner atomically.
  dbClient.write(mutations);
}

update 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
update test-instance example-db

SQL クエリまたは読み取り呼び出しを実行して、書き込んだばかりの値を取得することもできます。

クエリを実行するコードを次に示します。

static void queryMarketingBudget(DatabaseClient dbClient) {
  // Rows without an explicit value for MarketingBudget will have a MarketingBudget equal to
  // null.
  ResultSet resultSet =
      dbClient
          .singleUse()
          .executeQuery(Statement.of("SELECT SingerId, AlbumId, MarketingBudget FROM Albums"));
  while (resultSet.next()) {
    System.out.printf(
        "%d %d %s\n",
        resultSet.getLong("SingerId"),
        resultSet.getLong("AlbumId"),
        // We check that the value is non null. ResultSet getters can only be used to retrieve
        // non null values.
        resultSet.isNull("MarketingBudget") ? "NULL" : resultSet.getLong("MarketingBudget"));
  }
}

このクエリを実行するには、querymarketingbudget 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
querymarketingbudget test-instance example-db

以下のように表示されます。

1 1 100000
1 2 NULL
2 1 NULL
2 2 500000
2 3 NULL

データの更新

読み取り / 書き込みトランザクションで DML を使用してデータを更新できます。

executeUpdate() メソッドを使用して DML ステートメントを実行します。

static void writeWithTransactionUsingDml(DatabaseClient dbClient) {
  dbClient
      .readWriteTransaction()
      .run(
          new TransactionCallable<Void>() {
            @Override
            public Void run(TransactionContext transaction) throws Exception {
              // Transfer marketing budget from one album to another. We do it in a transaction to
              // ensure that the transfer is atomic.
              String sql1 =
                  "SELECT MarketingBudget from Albums WHERE SingerId = 1 and AlbumId = 1";
              ResultSet resultSet = transaction.executeQuery(Statement.of(sql1));
              long album1Budget = 0;
              while (resultSet.next()) {
                album1Budget = resultSet.getLong("MarketingBudget");
              }
              // Transaction will only be committed if this condition still holds at the time of
              // commit. Otherwise it will be aborted and the callable will be rerun by the
              // client library.
              if (album1Budget >= 300000) {
                String sql2 =
                    "SELECT MarketingBudget from Albums WHERE SingerId = 2 and AlbumId = 2";
                ResultSet resultSet2 = transaction.executeQuery(Statement.of(sql2));
                long album2Budget = 0;
                while (resultSet.next()) {
                  album2Budget = resultSet2.getLong("MarketingBudget");
                }
                long transfer = 200000;
                album2Budget += transfer;
                album1Budget -= transfer;
                Statement updateStatement =
                    Statement.newBuilder(
                        "UPDATE Albums "
                            + "SET MarketingBudget = @AlbumBudget "
                            + "WHERE SingerId = 1 and AlbumId = 1")
                        .bind("AlbumBudget")
                        .to(album1Budget)
                        .build();
                transaction.executeUpdate(updateStatement);
                Statement updateStatement2 =
                    Statement.newBuilder(
                        "UPDATE Albums "
                            + "SET MarketingBudget = @AlbumBudget "
                            + "WHERE SingerId = 2 and AlbumId = 2")
                        .bind("AlbumBudget")
                        .to(album2Budget)
                        .build();
                transaction.executeUpdate(updateStatement2);
              }
              return null;
            }
          });
}

writewithtransactionusingdml 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
writewithtransactionusingdml test-instance example-db

セカンダリ インデックスの使用

Albums から AlbumTitle の値が特定の範囲内である行すべてをフェッチしたいと仮定します。SQL ステートメントまたは読み取りインターフェースを使用して AlbumTitle 列からすべての値を読み取り、基準を満たしていない行を破棄することもできますが、この方法では処理量が大きくなります(特に、行数が多いテーブルの場合)。代わりに、テーブルにセカンダリ インデックスを作成することにより、主キー以外の列を検索するときの行の取得速度を上げることができます。

既存のテーブルにセカンダリ インデックスを追加するには、スキーマの更新が必要です。他のスキーマの更新と同様に、Cloud Spanner ではデータベースがトラフィックを提供している間にインデックスを追加できます。Cloud Spanner は、内部でインデックスにデータを書き込みます(「バックフィル」)。バックフィルには数分かかることがありますが、このプロセスの間に、データベースをオフラインにしたり、特定のテーブルや列への書き込みを避けたりする必要はありません。詳細については、インデックスのバックフィリングをご覧ください。

セカンダリ インデックスの追加

インデックスを追加するには、コマンドラインで gcloud コマンドライン ツールを使用するか、Java 用 Cloud Spanner クライアント ライブラリを使用してプログラミングによって行います。

コマンドラインから

データベースにインデックスを追加するには、次の CREATE INDEX コマンドを使用します。

gcloud spanner databases ddl update example-db --instance=test-instance \
  --ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'

以下のように表示されます。

DDL updating...done.

Java 用の Cloud Spanner クライアント ライブラリの使用

DatabaseAdminClient クラスの updateDatabaseDdl() メソッドを使用してインデックスを追加します。

static void addIndex(DatabaseAdminClient adminClient, DatabaseId dbId) {
  OperationFuture<Void, UpdateDatabaseDdlMetadata> op =
      adminClient
        .updateDatabaseDdl(
            dbId.getInstanceId().getInstance(),
            dbId.getDatabase(),
            Arrays.asList("CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"),
            null);
  try {
    // Initiate the request which returns an OperationFuture.
    op.get();
    System.out.println("Added AlbumsByAlbumTitle index");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

addindex 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
addindex test-instance example-db

インデックスの追加には数分かかる場合があります。インデックスが追加されると、次のように表示されます。

Added the AlbumsByAlbumTitle index.

インデックスを使用したクエリ

新しいインデックスを使用してクエリを実行するには、コマンドラインまたはクライアント ライブラリを使用します。

コマンドラインから

gcloud コマンドライン ツールで SQL ステートメントを実行し、["Aardvark", "Goo")AlbumsTitle の範囲に対して AlbumsByAlbumTitle インデックスを使用して Albums から AlbumIdAlbumTitleMarketingBudget を取得します。

gcloud spanner databases execute-sql example-db --instance=test-instance --sql='SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums@{FORCE_INDEX=AlbumsByAlbumTitle} WHERE AlbumTitle >= "Aardvark" AND AlbumTitle < "Goo"'

結果は次のようになります。

AlbumId  AlbumTitle               MarketingBudget
2        Go, Go, Go
2        Forever Hold Your Peace  300000

Java 用の Cloud Spanner クライアント ライブラリの使用

プログラマティックにインデックスを使用するコードは、前に使用したクエリのコードと似ています。

static void queryUsingIndex(DatabaseClient dbClient) {
  Statement statement =
      Statement
          // We use FORCE_INDEX hint to specify which index to use. For more details see
          // https://cloud.google.com/spanner/docs/query-syntax#from-clause
          .newBuilder(
              "SELECT AlbumId, AlbumTitle, MarketingBudget\n"
                  + "FROM Albums@{FORCE_INDEX=AlbumsByAlbumTitle}\n"
                  + "WHERE AlbumTitle >= @StartTitle AND AlbumTitle < @EndTitle")
          // We use @BoundParameters to help speed up frequently executed queries.
          //  For more details see https://cloud.google.com/spanner/docs/sql-best-practices
          .bind("StartTitle")
          .to("Aardvark")
          .bind("EndTitle")
          .to("Goo")
          .build();

  ResultSet resultSet = dbClient.singleUse().executeQuery(statement);
  while (resultSet.next()) {
    System.out.printf(
        "%d %s %s\n",
        resultSet.getLong("AlbumId"),
        resultSet.getString("AlbumTitle"),
        resultSet.isNull("MarketingBudget") ? "NULL" : resultSet.getLong("MarketingBudget"));
  }
}

queryindex 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
queryindex test-instance example-db

次のような出力が表示されます。

2 Go, Go, Go NULL
2 Forever Hold Your Peace 300000

詳細については、以下のリファレンスをご覧ください。

インデックスを使用した読み込み

インデックスを使用して読み取るには、ReadContext クラスの readUsingIndex() メソッドを使用します。

次のコードは、すべての AlbumId 列と AlbumTitle 列を AlbumsByAlbumTitle インデックスからフェッチします。

static void readUsingIndex(DatabaseClient dbClient) {
  ResultSet resultSet =
      dbClient
          .singleUse()
          .readUsingIndex(
              "Albums",
              "AlbumsByAlbumTitle",
              KeySet.all(),
              Arrays.asList("AlbumId", "AlbumTitle"));
  while (resultSet.next()) {
    System.out.printf("%d %s\n", resultSet.getLong(0), resultSet.getString(1));
  }
}

readindex 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
readindex test-instance example-db

以下のように表示されます。

2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk

STORING 句を使用したインデックスの追加

上記の読み取り例に MarketingBudget の列の読み取りが含まれていなかったことに気付かれたかもしれません。これは、Cloud Spanner の読み取りインターフェースが、インデックスとデータテーブルを結合してインデックスに格納されていない値を検索する機能をサポートしていないためです。

MarketingBudget のコピーをインデックスに格納する AlbumsByAlbumTitle の代替定義を作成します。

コマンドラインから

gcloud spanner databases ddl update example-db --instance=test-instance \
  --ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)'

インデックスの追加には数分かかる場合があります。インデックスが追加されると、次のように表示されます。

DDL updating...done.

Java 用の Cloud Spanner クライアント ライブラリの使用

DatabaseAdminClient クラスの updateDatabaseDdl() メソッドを使用し、STORING 句を指定してインデックスを追加します。

static void addStoringIndex(DatabaseAdminClient adminClient, DatabaseId dbId) {
  OperationFuture<Void, UpdateDatabaseDdlMetadata> op =
      adminClient
        .updateDatabaseDdl(
            dbId.getInstanceId().getInstance(),
            dbId.getDatabase(),
            Arrays.asList(
                "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) "
                    + "STORING (MarketingBudget)"),
            null);
  try {
    // Initiate the request which returns an OperationFuture.
    op.get();
    System.out.println("Added AlbumsByAlbumTitle2 index");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

addstoringindex 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
addstoringindex test-instance example-db

インデックスの追加には数分かかる場合があります。インデックスが追加されると、次のように表示されます。

Added the AlbumsByAlbumTitle2 index.

これで、インデックス AlbumsByAlbumTitle2 から AlbumIdAlbumTitleMarketingBudget 列をすべて取得する読み取りを実行できるようになります。

static void readStoringIndex(DatabaseClient dbClient) {
  // We can read MarketingBudget also from the index since it stores a copy of MarketingBudget.
  ResultSet resultSet =
      dbClient
          .singleUse()
          .readUsingIndex(
              "Albums",
              "AlbumsByAlbumTitle2",
              KeySet.all(),
              Arrays.asList("AlbumId", "AlbumTitle", "MarketingBudget"));
  while (resultSet.next()) {
    System.out.printf(
        "%d %s %s\n",
        resultSet.getLong(0),
        resultSet.getString(1),
        resultSet.isNull("MarketingBudget") ? "NULL" : resultSet.getLong("MarketingBudget"));
  }
}

readstoringindex 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
readstoringindex test-instance example-db

次のような出力が表示されます。

2 Forever Hold Your Peace 300000
2 Go, Go, Go NULL
1 Green NULL
3 Terrified NULL
1 Total Junk 300000

読み取り専用トランザクションを使用したデータの取得

同じタイムスタンプで複数の読み取りを実行する場合について考えます。読み取り専用トランザクションはトランザクションの commit 履歴の整合性のあるプレフィックスを監視しているので、アプリケーションは常に整合性のあるデータを取得できます。読み取り専用トランザクションの実行には、ReadOnlyTransaction オブジェクトを使用します。DatabaseClient クラスの readOnlyTransaction() メソッドを使用して、ReadOnlyTransaction オブジェクトを取得します。

同じ読み取り専用トランザクションでクエリと読み取りを実行する方法を次に示します。

static void readOnlyTransaction(DatabaseClient dbClient) {
  // ReadOnlyTransaction must be closed by calling close() on it to release resources held by it.
  // We use a try-with-resource block to automatically do so.
  try (ReadOnlyTransaction transaction = dbClient.readOnlyTransaction()) {
    ResultSet queryResultSet =
        transaction.executeQuery(
            Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"));
    while (queryResultSet.next()) {
      System.out.printf(
          "%d %d %s\n",
          queryResultSet.getLong(0), queryResultSet.getLong(1), queryResultSet.getString(2));
    }
    ResultSet readResultSet =
        transaction.read(
            "Albums", KeySet.all(), Arrays.asList("SingerId", "AlbumId", "AlbumTitle"));
    while (readResultSet.next()) {
      System.out.printf(
          "%d %d %s\n",
          readResultSet.getLong(0), readResultSet.getLong(1), readResultSet.getString(2));
    }
  }
}

readonlytransaction 引数を使用してサンプルを実行します。

java -jar target/spanner-google-cloud-samples-1.0.10-jar-with-dependencies.jar \
readonlytransaction test-instance example-db

次のような出力が表示されます。

2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified

クリーンアップ

このチュートリアルで使用したリソースの Google Cloud Platform アカウントが課金されないようにするため、作成したデータベースとインスタンスを削除します。

データベースの削除

インスタンスを削除すると、それに含まれるすべてのデータベースが自動的に削除されます。このステップでは、インスタンスを削除しないでデータベースを削除する方法を示します(インスタンスの料金は引き続き発生します)。

コマンドラインから

gcloud spanner databases delete example-db --instance=test-instance

GCP Console の使用

  1. Google Cloud Platform Console の [Cloud Spanner インスタンス] ページに移動します。
    [Cloud Spanner インスタンス] ページに移動
  2. インスタンスをクリックします。
  3. 削除するデータベースをクリックします。
  4. [データベースの詳細] ページで [削除] をクリックします。
  5. データベースを削除することを確認し、[削除] をクリックします。

インスタンスの削除

インスタンスを削除すると、そのインスタンスで作成されたすべてのデータベースが自動的に削除されます。

コマンドラインから

gcloud spanner instances delete test-instance

GCP Console の使用

  1. Google Cloud Platform Console の [Cloud Spanner インスタンス] ページに移動します。
    [Cloud Spanner インスタンス] ページに移動
  2. インスタンスをクリックします。
  3. [削除] をクリックします。
  4. インスタンスを削除することを確認し、[削除] をクリックします。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Cloud Spanner のドキュメント