Premiers pas avec Spanner en Java

---

Objectifs

Ce tutoriel vous explique comment effectuer les opérations suivantes à l'aide de la bibliothèque cliente Spanner pour Java:

• Créer une instance et une base de données Spanner
• Écrire ou lire des données dans la base de données, et exécuter des requêtes SQL sur ces données
• Mettre à jour le schéma de base de données
• Mettre à jour les données à l'aide d'une transaction en lecture/écriture
• Ajouter un index secondaire à la base de données
• Utiliser l'index pour lire et exécuter des requêtes SQL sur des données
• Récupérer des données à l'aide d'une transaction en lecture seule

Coûts

Ce tutoriel utilise Spanner, un composant facturable de Google Cloud. Pour en savoir plus sur le coût d'utilisation de Spanner, consultez la page Tarifs.

Avant de commencer

Pour obtenir les identifiants d'authentification permettant d'utiliser l'API Cloud Spanner, suivez les étapes décrites dans la section dédiée à la configuration qui traite des sujets suivants : création et définition d'un projet Google Cloud par défaut, activation de la facturation ainsi que de l'API Cloud Spanner, et configuration d'OAuth 2.0.

Veillez en particulier à exécuter gcloud auth application-default login pour configurer votre environnement de développement local avec des identifiants d'authentification.

Remarque : Si vous ne prévoyez pas de conserver les ressources que vous créez dans ce tutoriel, envisagez de créer un projet Google Cloud au lieu de sélectionner un projet existant. Une fois le tutoriel terminé, vous pouvez supprimer le projet en supprimant toutes les ressources associées.

Préparer l'environnement Java local

1. Installez les éléments suivants sur votre ordinateur de développement si ce n'est déjà fait :

   • Java 8 JDK (télécharger).
   • Maven 3 (télécharger)

2. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :

   git clone https://github.com/googleapis/java-spanner.git
   

3. Accédez au répertoire qui contient l'exemple de code Spanner:

   cd java-spanner/samples/snippets
   

Créer une instance

Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, qui alloue les ressources utilisées par les bases de données Spanner. Lorsque vous créez une instance, vous choisissez une configuration d'instance, qui détermine l'emplacement de stockage de vos données et le nombre de nœuds à utiliser. Ce dernier paramètre définit la quantité de ressources disponibles dans votre instance pour le stockage et la diffusion.

Exécutez la commande suivante pour créer une instance Spanner dans la région us-central1 avec un nœud:

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

Cette commande crée une instance présentant les caractéristiques suivantes :

• ID d'instance : test-instance
• Nom à afficher : Test Instance
• Configuration d'instance : regional-us-central1 (Les configurations régionales stockent les données dans une région, tandis que les configurations multirégionales les distribuent dans plusieurs régions. Pour en savoir plus, consultez À propos des instances.)
• Nombre de nœuds : 1 (node_count correspond à la quantité de ressources de stockage et de diffusion disponibles pour les bases de données de l'instance. Pour en savoir plus, consultez la section Nœuds et unités de traitement.)

Vous devriez obtenir le résultat suivant :

Creating instance...done.

Consulter des exemples de fichiers

Le dépôt d'exemples contient un exemple qui montre comment utiliser Spanner avec Java.

Créer une base de données

Créez une base de données nommée example-db dans l'instance test-instance en exécutant la commande suivante dans la ligne de commande.

GoogleSQL

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

PostgreSQL

java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
createpgdatabase test-instance example-db

Vous devriez obtenir le résultat suivant :

Created database [example-db]

Le code suivant crée une base de données et deux tables dans la base de données.

Remarque :Les exemples de code suivants utilisent ces deux tables. Si vous n'exécutez pas ce code, créez les tables à l'aide de la console Google Cloud ou de la gcloud CLI. Pour en savoir plus, consultez l'exemple de schéma.

GoogleSQL

static void createDatabase(DatabaseAdminClient dbAdminClient,
    InstanceName instanceName, String databaseId) {
  CreateDatabaseRequest createDatabaseRequest =
      CreateDatabaseRequest.newBuilder()
          .setCreateStatement("CREATE DATABASE `" + databaseId + "`")
          .setParent(instanceName.toString())
          .addAllExtraStatements(Arrays.asList(
              "CREATE TABLE Singers ("
                  + "  SingerId   INT64 NOT NULL,"
                  + "  FirstName  STRING(1024),"
                  + "  LastName   STRING(1024),"
                  + "  SingerInfo BYTES(MAX),"
                  + "  FullName STRING(2048) AS "
                  + "  (ARRAY_TO_STRING([FirstName, LastName], \" \")) STORED"
                  + ") PRIMARY KEY (SingerId)",
              "CREATE TABLE Albums ("
                  + "  SingerId     INT64 NOT NULL,"
                  + "  AlbumId      INT64 NOT NULL,"
                  + "  AlbumTitle   STRING(MAX)"
                  + ") PRIMARY KEY (SingerId, AlbumId),"
                  + "  INTERLEAVE IN PARENT Singers ON DELETE CASCADE")).build();
  try {
    // Initiate the request which returns an OperationFuture.
    com.google.spanner.admin.database.v1.Database db =
        dbAdminClient.createDatabaseAsync(createDatabaseRequest).get();
    System.out.println("Created database [" + db.getName() + "]");
  } 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);
  }
}

PostgreSQL

static void createPostgreSqlDatabase(
    DatabaseAdminClient dbAdminClient, String projectId, String instanceId, String databaseId) {
  final CreateDatabaseRequest request =
      CreateDatabaseRequest.newBuilder()
          .setCreateStatement("CREATE DATABASE \"" + databaseId + "\"")
          .setParent(InstanceName.of(projectId, instanceId).toString())
          .setDatabaseDialect(DatabaseDialect.POSTGRESQL).build();

  try {
    // Initiate the request which returns an OperationFuture.
    Database db = dbAdminClient.createDatabaseAsync(request).get();
    System.out.println("Created database [" + db.getName() + "]");
  } 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);
  }
}
static void createTableUsingDdl(DatabaseAdminClient dbAdminClient, DatabaseName databaseName) {
  try {
    // Initiate the request which returns an OperationFuture.
    dbAdminClient.updateDatabaseDdlAsync(
        databaseName,
        Arrays.asList(
            "CREATE TABLE Singers ("
                + "  SingerId   bigint NOT NULL,"
                + "  FirstName  character varying(1024),"
                + "  LastName   character varying(1024),"
                + "  SingerInfo bytea,"
                + "  FullName character varying(2048) GENERATED "
                + "  ALWAYS AS (FirstName || ' ' || LastName) STORED,"
                + "  PRIMARY KEY (SingerId)"
                + ")",
            "CREATE TABLE Albums ("
                + "  SingerId     bigint NOT NULL,"
                + "  AlbumId      bigint NOT NULL,"
                + "  AlbumTitle   character varying(1024),"
                + "  PRIMARY KEY (SingerId, AlbumId)"
                + ") INTERLEAVE IN PARENT Singers ON DELETE CASCADE")).get();
    System.out.println("Created Singers & Albums tables in database: [" + databaseName + "]");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw SpannerExceptionFactory.asSpannerException(e);
  } 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);
  }
}

L'étape suivante consiste à écrire des données dans la base de données.

Créer un client de base de données

Pour pouvoir effectuer des opérations de lecture ou d'écriture, vous devez créer un objet DatabaseClient. Vous pouvez considérer un objet DatabaseClient comme une connexion à une base de données. Toutes vos interactions avec Spanner doivent s'effectuer par le biais de cet objet DatabaseClient. En général, vous devez créer un objet DatabaseClient lorsque votre application démarre. Vous réutiliserez ensuite cet objet DatabaseClient pour lire, écrire et exécuter des transactions.

GoogleSQL

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

  // Use client here...
} finally {
  if (dbAdminClient != null) {
    if (!dbAdminClient.isShutdown() || !dbAdminClient.isTerminated()) {
      dbAdminClient.close();
    }
  }
  spanner.close();
}

PostgreSQL

SpannerOptions options = SpannerOptions.newBuilder().build();
Spanner spanner = options.getService();
DatabaseAdminClient dbAdminClient = null;
try {
  DatabaseClient dbClient = spanner.getDatabaseClient(db);
  dbAdminClient = spanner.createDatabaseAdminClient();
} finally {
  if (dbAdminClient != null) {
    if (!dbAdminClient.isShutdown() || !dbAdminClient.isTerminated()) {
      dbAdminClient.close();
    }
  }
  spanner.close();
}

Chaque client utilise des ressources dans Spanner. Il est donc recommandé de fermer les clients inutiles en appelant close().

Pour en savoir plus, consultez la documentation de référence Javadoc sur DatabaseClient.

Écrire des données avec le langage LMD

Vous pouvez insérer des données à l'aide du langage de manipulation de données (LMD) dans une transaction en lecture/écriture.

L'exécution d'une instruction LMD s'effectue via la méthode executeUpdate().

static void writeUsingDml(DatabaseClient dbClient) {
  // Insert 4 singer records
  dbClient
      .readWriteTransaction()
      .run(transaction -> {
        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;
      });
}

Exécutez l'exemple en utilisant l'argument writeusingdml.

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

Vous devriez obtenir le résultat suivant :

4 records inserted.

Remarque : La taille des commits est limitée. Pour en savoir plus, consultez la section Limites de création, lecture, modification et suppression des données.

Écrire des données avec des mutations

Vous pouvez également insérer des données à l'aide de mutations.

Vous pouvez écrire des données à l'aide d'un objet Mutation. Un objet Mutation est un conteneur pour les opérations de mutation. Un Mutation représente une séquence d'insertions, de mises à jour et de suppressions que Spanner applique de manière atomique à différentes lignes et tables d'une base de données Spanner.

La méthode newInsertBuilder() de la classe Mutation construit une mutation INSERT, qui insère une nouvelle ligne dans une table. Si la ligne existe déjà, l'écriture échoue. Vous pouvez également utiliser la méthode newInsertOrUpdateBuilder pour créer une mutation INSERT_OR_UPDATE, qui met à jour les valeurs de colonne si la ligne existe déjà.

La méthode write() de la classe DatabaseClient écrit les mutations. Toutes les mutations d'un même lot sont appliquées de manière atomique.

Le code ci-dessous montre comment écrire les données à l'aide de mutations :

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);
}

Exécutez l'exemple en utilisant l'argument write.

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

Vous devriez voir la commande s'exécuter avec succès.

Remarque : La taille des commits est limitée. Pour en savoir plus, consultez la section Limites de création, lecture, modification et suppression des données.

Interroger des données à l'aide de SQL

Spanner accepte une interface SQL pour la lecture des données. Vous pouvez accéder à cette interface via la ligne de commande à l'aide de Google Cloud CLI ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Java.

Sur la ligne de commande

Exécutez l'instruction SQL suivante pour lire les valeurs de toutes les colonnes de la table Albums :

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

Remarque :Pour en savoir plus sur GoogleSQL, consultez Syntaxe des requêtes dans GoogleSQL. Pour en savoir plus sur PostgreSQL, consultez Structure lexicale et syntaxe PostgreSQL.

Vous devez obtenir le résultat suivant :

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

Utiliser la bibliothèque cliente Spanner pour Java

Vous pouvez non seulement exécuter une instruction SQL via la ligne de commande, mais également appliquer la même instruction SQL de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Java.

Les méthodes et classes ci-dessous sont utilisées pour exécuter la requête SQL :

• Méthode singleUse() de la classe DatabaseClient: utilisez cette méthode pour lire la valeur d'une ou de plusieurs colonnes dans une ou plusieurs lignes d'une table Spanner. singleUse() renvoie un objet ReadContext, qui permet d'exécuter une instruction de lecture ou une instruction SQL.
• Méthode executeQuery() de la classe ReadContext : utilisez cette méthode pour exécuter une requête sur une base de données.
• Classe Statement : utilisez cette classe pour créer une chaîne SQL.
• Classe ResultSet : utilisez cette classe pour accéder aux données renvoyées par une instruction SQL ou un appel de lecture.

Le code ci-dessous permet d'exécuter la requête et d'accéder aux données.

static void query(DatabaseClient dbClient) {
  try (ResultSet resultSet =
      dbClient
          .singleUse() // Execute a single read or query against Cloud Spanner.
          .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));
    }
  }
}

Exécutez l'exemple en utilisant l'argument query.

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

Vous devriez obtenir le résultat suivant :

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

Requête utilisant un paramètre SQL

Si votre application exécute une requête fréquemment, vous pouvez améliorer ses performances en la paramétrant. La requête paramétrique résultante peut être mise en cache et réutilisée, ce qui réduit les coûts de compilation. Pour en savoir plus, consultez la section Utiliser des paramètres de requête pour accélérer les requêtes fréquemment exécutées.

Voici un exemple d'utilisation d'un paramètre de la clause WHERE pour interroger des enregistrements contenant une valeur spécifique pour LastName.

GoogleSQL

static void queryWithParameter(DatabaseClient dbClient) {
  Statement statement =
      Statement.newBuilder(
              "SELECT SingerId, FirstName, LastName "
                  + "FROM Singers "
                  + "WHERE LastName = @lastName")
          .bind("lastName")
          .to("Garcia")
          .build();
  try (ResultSet resultSet = dbClient.singleUse().executeQuery(statement)) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %s %s\n",
          resultSet.getLong("SingerId"),
          resultSet.getString("FirstName"),
          resultSet.getString("LastName"));
    }
  }
}

PostgreSQL

static void queryWithParameter(DatabaseClient dbClient) {
  Statement statement =
      Statement.newBuilder(
              "SELECT singerid AS \"SingerId\", "
                  + "firstname as \"FirstName\", lastname as \"LastName\" "
                  + "FROM Singers "
                  + "WHERE LastName = $1")
          .bind("p1")
          .to("Garcia")
          .build();
  try (ResultSet resultSet = dbClient.singleUse().executeQuery(statement)) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %s %s\n",
          resultSet.getLong("SingerId"),
          resultSet.getString("FirstName"),
          resultSet.getString("LastName"));
    }
  }
}

Exécutez l'exemple à l'aide de l'argument queryWithParameter.

java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
    querywithparameter test-instance example-db

Vous devriez obtenir le résultat suivant :

12 Melissa Garcia

Lire des données à l'aide de l'API de lecture

En plus de son interface SQL, Spanner accepte également une interface de lecture.

Utilisez la méthode read() de la classe ReadContext pour lire les lignes de la base de données. Utilisez un objet KeySet pour définir une collection de clés et de plages de clés à lire.

Le code ci-dessous permet de lire les données.

static void read(DatabaseClient dbClient) {
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .read(
              "Albums",
              KeySet.all(), // Read all rows in a table.
              Arrays.asList("SingerId", "AlbumId", "AlbumTitle"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s\n", resultSet.getLong(0), resultSet.getLong(1), resultSet.getString(2));
    }
  }
}

Exécutez l'exemple en utilisant l'argument read.

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

Un résultat semblable à celui-ci s'affiche :

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

Mettre à jour le schéma de base de données

Supposons que vous deviez ajouter la colonne MarketingBudget à la table Albums. L'ajout d'une colonne à une table existante nécessite une mise à jour du schéma de base de données. Spanner permet de mettre à jour le schéma d'une base de données pendant que celle-ci continue de diffuser le trafic. Les mises à jour de schéma ne nécessitent pas de mettre la base de données hors connexion et ne verrouillent pas des tables ou des colonnes entières. Vous pouvez continuer à écrire des données dans la base de données pendant la mise à jour du schéma. Pour en savoir plus sur les mises à jour de schéma acceptées et les performances liées aux modifications de schéma, consultez la page Effectuer des mises à jour de schéma.

Ajouter une colonne

Vous pouvez ajouter une colonne via la ligne de commande à l'aide de Google Cloud CLI, ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Java.

Sur la ligne de commande

Pour ajouter la colonne à la table, utilisez la commande ALTER TABLE suivante :

GoogleSQL

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

PostgreSQL

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

Vous devriez obtenir le résultat suivant :

Schema updating...done.

Utiliser la bibliothèque cliente Spanner pour Java

Utilisez la méthode updateDatabaseDdl() de la classe DatabaseAdminClient pour modifier le schéma:

GoogleSQL

static void addMarketingBudget(DatabaseAdminClient adminClient, DatabaseName databaseName) {
  try {
    // Initiate the request which returns an OperationFuture.
    adminClient.updateDatabaseDdlAsync(
        databaseName,
        Arrays.asList("ALTER TABLE Albums ADD COLUMN MarketingBudget INT64")).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);
  }
}

PostgreSQL

static void addMarketingBudget(DatabaseAdminClient adminClient, DatabaseName databaseName) {
  try {
    // Initiate the request which returns an OperationFuture.
    adminClient.updateDatabaseDdlAsync(
        databaseName,
        Arrays.asList("ALTER TABLE Albums ADD COLUMN MarketingBudget bigint")).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);
  }
}

Exécutez l'exemple en utilisant l'argument addmarketingbudget.

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

Vous devriez voir les éléments suivants :

Added MarketingBudget column.

Écrire des données dans la nouvelle colonne

Le code ci-dessous permet d'écrire des données dans la nouvelle colonne. Il définit MarketingBudget sur 100000 pour la ligne correspondant à la clé Albums(1, 1) et sur 500000 pour la ligne correspondant à la clé Albums(2, 2).

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);
}

Exécutez l'exemple en utilisant l'argument update.

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

Vous pouvez également exécuter une requête SQL ou un appel de lecture pour récupérer les valeurs que vous venez d'écrire.

Le code permettant d'exécuter la requête est présenté ci-dessous.

GoogleSQL

static void queryMarketingBudget(DatabaseClient dbClient) {
  // Rows without an explicit value for MarketingBudget will have a MarketingBudget equal to
  // null. A try-with-resource block is used to automatically release resources held by
  // ResultSet.
  try (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"));
    }
  }
}

PostgreSQL

static void queryMarketingBudget(DatabaseClient dbClient) {
  // Rows without an explicit value for MarketingBudget will have a MarketingBudget equal to
  // null. A try-with-resource block is used to automatically release resources held by
  // ResultSet.
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .executeQuery(Statement.of("SELECT singerid as \"SingerId\", "
              + "albumid as \"AlbumId\", marketingbudget as \"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"));
    }
  }
}

Pour mettre en œuvre cette requête, exécutez l'exemple en utilisant l'argument querymarketingbudget.

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

Vous devriez obtenir le résultat suivant :

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

Mettre à jour des données

Vous pouvez mettre à jour des données à l'aide du langage LMD dans une transaction en lecture/écriture.

Pour exécuter une instruction LMD, utilisez la méthode executeUpdate().

GoogleSQL

static void writeWithTransactionUsingDml(DatabaseClient dbClient) {
  dbClient
      .readWriteTransaction()
      .run(transaction -> {
        // 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 = 2 and AlbumId = 2";
        ResultSet resultSet = transaction.executeQuery(Statement.of(sql1));
        long album2Budget = 0;
        while (resultSet.next()) {
          album2Budget = 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.
        long transfer = 200000;
        if (album2Budget >= transfer) {
          String sql2 =
              "SELECT MarketingBudget from Albums WHERE SingerId = 1 and AlbumId = 1";
          ResultSet resultSet2 = transaction.executeQuery(Statement.of(sql2));
          long album1Budget = 0;
          while (resultSet2.next()) {
            album1Budget = resultSet2.getLong("MarketingBudget");
          }
          album1Budget += transfer;
          album2Budget -= 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;
      });
}

PostgreSQL

static void writeWithTransactionUsingDml(DatabaseClient dbClient) {
  dbClient
      .readWriteTransaction()
      .run(transaction -> {
        // 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 as \"MarketingBudget\" from Albums WHERE "
                + "SingerId = 2 and AlbumId = 2";
        ResultSet resultSet = transaction.executeQuery(Statement.of(sql1));
        long album2Budget = 0;
        while (resultSet.next()) {
          album2Budget = 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.
        long transfer = 200000;
        if (album2Budget >= transfer) {
          String sql2 =
              "SELECT marketingbudget as \"MarketingBudget\" from Albums WHERE "
                  + "SingerId = 1 and AlbumId = 1";
          ResultSet resultSet2 = transaction.executeQuery(Statement.of(sql2));
          long album1Budget = 0;
          while (resultSet2.next()) {
            album1Budget = resultSet2.getLong("MarketingBudget");
          }
          album1Budget += transfer;
          album2Budget -= transfer;
          Statement updateStatement =
              Statement.newBuilder(
                      "UPDATE Albums "
                          + "SET MarketingBudget = $1"
                          + "WHERE SingerId = 1 and AlbumId = 1")
                  .bind("p1")
                  .to(album1Budget)
                  .build();
          transaction.executeUpdate(updateStatement);
          Statement updateStatement2 =
              Statement.newBuilder(
                      "UPDATE Albums "
                          + "SET MarketingBudget = $1"
                          + "WHERE SingerId = 2 and AlbumId = 2")
                  .bind("p1")
                  .to(album2Budget)
                  .build();
          transaction.executeUpdate(updateStatement2);
        }
        return null;
      });
}

Exécutez l'exemple en utilisant l'argument writewithtransactionusingdml.

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

Remarque :Vous pouvez également mettre à jour des données à l'aide de mutations.

Utiliser un index secondaire

Supposons que vous vouliez récupérer toutes les lignes de la table Albums dont les valeurs AlbumTitle sont comprises dans une certaine plage. Vous pouvez lire toutes les valeurs de la colonne AlbumTitle à l'aide d'une instruction SQL ou d'un appel de lecture, puis supprimer les lignes qui ne correspondent pas aux critères. Toutefois, cette analyse complète de la table est coûteuse, en particulier si celle-ci comporte beaucoup de lignes. Vous pouvez accélérer la récupération des lignes lors des recherches effectuées en fonction des colonnes de clé non primaire en créant un index secondaire pour la table.

L'ajout d'un index secondaire à une table existante nécessite une mise à jour du schéma. Comme les autres mises à jour de schéma, Spanner permet l'ajout d'un index pendant que la base de données continue de diffuser du trafic. Spanner remplit automatiquement l'index avec vos données existantes. Les remplissages peuvent prendre quelques minutes. Toutefois, ce processus ne requiert pas la mise hors connexion de la base de données et ne vous empêche pas d'écrire dans la table indexée. Pour en savoir plus, consultez Ajouter un index secondaire.

Une fois que vous avez ajouté un index secondaire, Spanner l'utilise automatiquement pour les requêtes SQL susceptibles de s'exécuter plus rapidement avec l'index. Si vous utilisez l'interface de lecture, vous devez spécifier l'index que vous souhaitez utiliser.

Ajouter un index secondaire

Vous pouvez ajouter un index via la ligne de commande à l'aide de la gcloud CLI ou de manière automatisée à l'aide de la bibliothèque cliente Spanner pour Java.

Sur la ligne de commande

Exécutez la commande CREATE INDEX suivante pour ajouter un index à la base de données :

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

Vous devriez obtenir le résultat suivant :

Schema updating...done.

Utiliser la bibliothèque cliente Spanner pour Java

Utilisez la méthode updateDatabaseDdl() de la classe DatabaseAdminClient pour ajouter un index:

static void addIndex(DatabaseAdminClient adminClient, DatabaseName databaseName) {
  try {
    // Initiate the request which returns an OperationFuture.
    adminClient.updateDatabaseDdlAsync(
        databaseName,
        Arrays.asList("CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)")).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);
  }
}

Exécutez l'exemple en utilisant l'argument addindex.

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

L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :

Added the AlbumsByAlbumTitle index.

Lire des données avec l'index

Pour les requêtes SQL, Spanner utilise automatiquement un index approprié. Dans l'interface de lecture, vous devez spécifier l'index dans votre requête.

Pour utiliser l'index dans l'interface de lecture, utilisez la méthode readUsingIndex() de la classe ReadContext.

Le code ci-dessous permet de récupérer toutes les colonnes AlbumId et AlbumTitle à partir de l'index AlbumsByAlbumTitle.

static void readUsingIndex(DatabaseClient dbClient) {
  try (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));
    }
  }
}

Exécutez l'exemple en utilisant l'argument readindex.

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

Vous devriez obtenir le résultat suivant :

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

Ajouter un index pour les lectures sur index uniquement

Vous avez peut-être remarqué que l'exemple de lecture précédent n'inclut pas la lecture de la colonne MarketingBudget. En effet, l'interface de lecture de Spanner ne permet pas de joindre un index à une table de données pour rechercher des valeurs qui ne sont pas stockées dans l'index.

Créez une autre définition de l'index AlbumsByAlbumTitle qui stocke dans l'index une copie de MarketingBudget.

Sur la ligne de commande

GoogleSQL

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

PostgreSQL

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

L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :

Schema updating...done.

Utiliser la bibliothèque cliente Spanner pour Java

Utilisez la méthode updateDatabaseDdl() de la classe DatabaseAdminClient pour ajouter un index avec une clause STORING pour GoogleSQL et une clause INCLUDE pour PostgreSQL:

GoogleSQL

static void addStoringIndex(DatabaseAdminClient adminClient, DatabaseName databaseName) {
  try {
    // Initiate the request which returns an OperationFuture.
    adminClient.updateDatabaseDdlAsync(
        databaseName,
        Arrays.asList(
            "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) "
                + "STORING (MarketingBudget)")).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);
  }
}

PostgreSQL

static void addStoringIndex(DatabaseAdminClient adminClient, DatabaseName databaseName) {
  try {
    // Initiate the request which returns an OperationFuture.
    adminClient.updateDatabaseDdlAsync(
        databaseName,
        Arrays.asList(
            "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) "
                + "INCLUDE (MarketingBudget)")).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);
  }
}

Exécutez l'exemple en utilisant l'argument addstoringindex.

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

L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, vous devriez obtenir le résultat suivant :

Added AlbumsByAlbumTitle2 index

Vous pouvez maintenant exécuter une opération de lecture permettant de récupérer toutes les colonnes AlbumId, AlbumTitle et MarketingBudget à partir de l'index AlbumsByAlbumTitle2 :

static void readStoringIndex(DatabaseClient dbClient) {
  // We can read MarketingBudget also from the index since it stores a copy of MarketingBudget.
  try (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"));
    }
  }
}

Exécutez l'exemple en utilisant l'argument readstoringindex.

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

Un résultat semblable à celui-ci s'affiche :

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

Récupérer des données à l'aide de transactions en lecture seule

Supposons que vous souhaitiez exécuter plusieurs opérations de lecture avec le même horodatage. Les transactions en lecture seule tiennent compte d'un préfixe cohérent de l'historique de commit des transactions, de sorte que votre application obtienne toujours des données cohérentes. Pour exécuter des transactions en lecture seule, utilisez un objet ReadOnlyTransaction. Utilisez la méthode readOnlyTransaction() de la classe DatabaseClient pour obtenir un objet ReadOnlyTransaction.

L'exemple ci-dessous montre comment exécuter une requête et effectuer une lecture dans la même transaction en lecture seule.

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));
    }
    try (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));
      }
    }
  }
}

Exécutez l'exemple en utilisant l'argument readonlytransaction.

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

Un résultat semblable à celui-ci s'affiche :

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

Nettoyage

Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Cloud Billing pour les ressources utilisées dans ce tutoriel, supprimez la base de données et l'instance que vous avez créées.

Supprimer la base de données

Si vous supprimez une instance, toutes les bases de données qu'elle contient sont automatiquement supprimées. Cette étape montre comment supprimer une base de données sans supprimer l'instance. Des frais continueront à vous être facturés pour cette dernière.

Sur la ligne de commande

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

Utiliser la console Google Cloud

1. Accédez à la page Instances de Spanner dans la console Google Cloud.

   Accéder à la page Instances

2. Cliquez sur l'instance.

3. Cliquez sur la base de données que vous souhaitez supprimer.

4. Sur la page Détails de la base de données, cliquez sur Supprimer.

5. Confirmez que vous souhaitez supprimer la base de données, puis cliquez sur Supprimer.

Supprimer l'instance

La suppression d'une instance supprime automatiquement toutes les bases de données créées dans cette instance.

Sur la ligne de commande

gcloud spanner instances delete test-instance

Utiliser la console Google Cloud

1. Accédez à la page Instances de Spanner dans la console Google Cloud.

   Accéder à la page Instances

2. Cliquez sur votre instance.

3. Cliquez sur Supprimer.

4. Confirmez que vous souhaitez supprimer l'instance, puis cliquez sur Supprimer.

Étapes suivantes

• Essayez le module Spring Data pour Spanner.

• Découvrez comment accéder à Spanner à l'aide d'une instance de machine virtuelle.

• Pour en savoir plus sur les identifiants d'autorisation et d'authentification, consultez la section S'authentifier auprès des services cloud à l'aide de bibliothèques clientes.

• En savoir plus sur les bonnes pratiques de conception de schémas Spanner.