Premiers pas avec Spanner en C++

---

Remarque sur l'interface PostgreSQL : Les exemples de cette rubrique sont destinés aux bases de données utilisant le dialecte GoogleSQL.

Objectifs

Remarque :Ce tutoriel utilise la classe Bibliothèque cliente C++ pour Linux, avec Bazel comme outil de compilation. Si vous souhaitez utiliser une autre de développement logiciel ou de la plate-forme, reportez-vous aux instructions samples/ sur GitHub.

Ce tutoriel décrit les étapes suivantes à l'aide de l'API Spanner pour C++:

• 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 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 votre environnement C++ local

1. Clonez le dépôt de l'exemple d'application sur votre machine locale :

   git clone https://github.com/googleapis/google-cloud-cpp $HOME/google-cloud-cpp
   

2. Installez Bazel pour Linux en suivant ces instructions.

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

   cd $HOME/google-cloud-cpp
   

4. Créez des exemples à l'aide de la commande suivante :

   bazel build //google/cloud/spanner/samples:samples
   

5. Configurez l'authentification et l'autorisation pour le projet google-cloud-cpp

   gcloud auth application-default login
   

6. Créez une variable d'environnement appelée GCLOUD_PROJECT. Remplacez [MY_PROJECT_ID] par l'ID de votre projet Google Cloud. Vous trouverez cet ID dans le fichier Bienvenue.

   export GCLOUD_PROJECT=[MY_PROJECT_ID]
   

Créer une instance

Lorsque vous utilisez Spanner pour la première fois, vous devez créer une instance, l'allocation des 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 1 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 la section À 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 par défaut.)

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 C++.

Examinez le fichier google/cloud/spanner/samples/samples.cc, qui montre comment créer une base de données et modifier un schéma de base de données. Les données utilisent l'exemple de schéma présenté sur la page Schéma et modèle de données.

Créer une base de données

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

bazel run //google/cloud/spanner/samples:samples -- \
    create-database $GCLOUD_PROJECT test-instance example-db

Remarque :Certaines syntaxes de Bazel, telles que --, ressemblent à la syntaxe bash, mais ce n'est pas le cas. Pour en savoir plus, consultez les commandes et options de Bazel. .

Vous devriez obtenir le résultat suivant :

Created database [projects/${GCLOUD_PROJECT}/instances/test-instance/databases/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, puis créer les tables à l'aide de la console Google Cloud ou gcloud CLI. Pour en savoir plus, consultez l'exemple de schéma.

void CreateDatabase(google::cloud::spanner_admin::DatabaseAdminClient client,
                    std::string const& project_id,
                    std::string const& instance_id,
                    std::string const& database_id) {
  google::cloud::spanner::Database database(project_id, instance_id,
                                            database_id);
  google::spanner::admin::database::v1::CreateDatabaseRequest request;
  request.set_parent(database.instance().FullName());
  request.set_create_statement("CREATE DATABASE `" + database.database_id() +
                               "`");
  request.add_extra_statements(R"""(
      CREATE TABLE Singers (
          SingerId   INT64 NOT NULL,
          FirstName  STRING(1024),
          LastName   STRING(1024),
          SingerInfo BYTES(MAX),
          FullName   STRING(2049)
              AS (ARRAY_TO_STRING([FirstName, LastName], " ")) STORED
      ) PRIMARY KEY (SingerId))""");
  request.add_extra_statements(R"""(
      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)""");
  auto db = client.CreateDatabase(request).get();
  if (!db) throw std::move(db).status();
  std::cout << "Database " << db->name() << " created.\n";
}

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 Client :

auto database = spanner::Database(project_id, instance_id, database_id);
auto connection = spanner::MakeConnection(database);
auto client = spanner::Client(connection);

Un Client vous permet de lire, d'écrire, d'interroger et d'exécuter des transactions sur un Spanner. En général, vous devez créer un Client lorsque votre application démarre. Vous réutiliserez ensuite ce Client pour lire, écrire et exécuter des transactions. Chaque client utilise des ressources dans Spanner. Le destructeur de Client nettoiera automatiquement les ressources Client, y compris les connexions réseau.

En savoir plus sur Client dans la référence C++ de Google Cloud Spanner.

É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.

Vous utilisez la fonction Client::ExecuteDml() pour exécuter une instruction LMD.

void DmlGettingStartedInsert(google::cloud::spanner::Client client) {
  using ::google::cloud::StatusOr;
  namespace spanner = ::google::cloud::spanner;

  auto commit_result = client.Commit(
      [&client](spanner::Transaction txn) -> StatusOr<spanner::Mutations> {
        auto insert = client.ExecuteDml(
            std::move(txn),
            spanner::SqlStatement(
                "INSERT INTO Singers (SingerId, FirstName, LastName) VALUES"
                " (12, 'Melissa', 'Garcia'),"
                " (13, 'Russell', 'Morales'),"
                " (14, 'Jacqueline', 'Long'),"
                " (15, 'Dylan', 'Shaw')"));
        if (!insert) return std::move(insert).status();
        return spanner::Mutations{};
      });
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << "Insert was successful [spanner_dml_getting_started_insert]\n";
}

Exécutez l'exemple en utilisant l'argument getting-started-insert.

bazel run //google/cloud/spanner/samples:samples -- \
    getting-started-insert $GCLOUD_PROJECT test-instance example-db

Vous devriez obtenir le résultat suivant :

Insert was successful [spanner_dml_getting_started_insert]

Remarque :La taille du commit est limitée. Voir Limite CRUD pour en savoir plus.

É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 Client. La méthode Client::Commit() permet la création et le commit d'une transaction pour les écritures, lesquelles s'exécutent de manière atomique à un même instant logique dans les colonnes, les lignes et les tables d'une base de données.

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

void InsertData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto insert_singers = spanner::InsertMutationBuilder(
                            "Singers", {"SingerId", "FirstName", "LastName"})
                            .EmplaceRow(1, "Marc", "Richards")
                            .EmplaceRow(2, "Catalina", "Smith")
                            .EmplaceRow(3, "Alice", "Trentor")
                            .EmplaceRow(4, "Lea", "Martin")
                            .EmplaceRow(5, "David", "Lomond")
                            .Build();

  auto insert_albums = spanner::InsertMutationBuilder(
                           "Albums", {"SingerId", "AlbumId", "AlbumTitle"})
                           .EmplaceRow(1, 1, "Total Junk")
                           .EmplaceRow(1, 2, "Go, Go, Go")
                           .EmplaceRow(2, 1, "Green")
                           .EmplaceRow(2, 2, "Forever Hold Your Peace")
                           .EmplaceRow(2, 3, "Terrified")
                           .Build();

  auto commit_result =
      client.Commit(spanner::Mutations{insert_singers, insert_albums});
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << "Insert was successful [spanner_insert_data]\n";
}

Exécutez l'exemple en utilisant l'argument insert-data.

bazel run //google/cloud/spanner/samples:samples -- \
    insert-data $GCLOUD_PROJECT test-instance example-db

Vous devriez obtenir le résultat suivant :

Insert was successful [spanner_insert_data]

Remarque :La taille du commit est limitée. Voir Limite CRUD pour en savoir plus.

Interroger des données à l'aide de SQL

Spanner accepte une interface SQL pour la lecture des données, que vous pouvez via la ligne de commande à l'aide de la Google Cloud CLI de manière programmatique à l'aide la bibliothèque cliente Spanner pour C++.

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 databases 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 la page Structure lexicale et syntaxe de 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 C++

Outre l'exécution d'une instruction SQL via la ligne de commande, vous pouvez utiliser le la même instruction SQL de manière programmatique à l'aide de la bibliothèque cliente Spanner C++

Vous utilisez la fonction Client::ExecuteQuery() pour exécuter la requête SQL. Le code ci-dessous permet d'exécuter la requête et d'accéder aux données.

void QueryData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  spanner::SqlStatement select("SELECT SingerId, LastName FROM Singers");
  using RowType = std::tuple<std::int64_t, std::string>;
  auto rows = client.ExecuteQuery(std::move(select));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "LastName: " << std::get<1>(*row) << "\n";
  }

  std::cout << "Query completed for [spanner_query_data]\n";
}

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

bazel run //google/cloud/spanner/samples:samples -- \
    query-data $GCLOUD_PROJECT test-instance example-db

Vous devriez obtenir le résultat suivant :

SingerId: 1     LastName: Richards
SingerId: 2     LastName: Smith
SingerId: 3     LastName: Trentor
SingerId: 4     LastName: Martin
SingerId: 5     LastName: Lomond
SingerId: 12    LastName: Garcia
SingerId: 13    LastName: Morales
SingerId: 14    LastName: Long
SingerId: 15    LastName: Shaw

Requête utilisant un paramètre SQL

Si votre application comporte une requête fréquemment exécutée, vous pouvez améliorer ses performances en les paramétrant. La requête paramétrique obtenue peut être mise en cache et réutilisée, ce qui réduit les coûts de compilation. Pour en savoir plus, consultez Utilisez 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 dans la clause WHERE pour enregistrements de requête contenant une valeur spécifique pour LastName.

void QueryWithParameter(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  spanner::SqlStatement select(
      "SELECT SingerId, FirstName, LastName FROM Singers"
      " WHERE LastName = @last_name",
      {{"last_name", spanner::Value("Garcia")}});
  using RowType = std::tuple<std::int64_t, std::string, std::string>;
  auto rows = client.ExecuteQuery(std::move(select));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "FirstName: " << std::get<1>(*row) << "\t";
    std::cout << "LastName: " << std::get<2>(*row) << "\n";
  }

  std::cout << "Query completed for [spanner_query_with_parameter]\n";
}

Exécutez l'exemple à l'aide de la commande query-with-parameter.

bazel run //google/cloud/spanner/samples:samples -- \
    query-with-parameter $GCLOUD_PROJECT test-instance example-db

Vous devriez obtenir le résultat suivant :

SingerId: 12    FirstName: Melissa      LastName: Garcia

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

En plus de l'interface SQL de Spanner, Spanner accepte de lecture.

Utilisez la fonction Client::Read() 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.

void ReadData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  auto rows = client.Read("Albums", google::cloud::spanner::KeySet::All(),
                          {"SingerId", "AlbumId", "AlbumTitle"});
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "AlbumId: " << std::get<1>(*row) << "\t";
    std::cout << "AlbumTitle: " << std::get<2>(*row) << "\n";
  }

  std::cout << "Read completed for [spanner_read_data]\n";
}

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

bazel run //google/cloud/spanner/samples:samples -- \
    read-data $GCLOUD_PROJECT test-instance example-db

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

SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: 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, tandis que continue de diffuser du trafic. Les mises à jour de schéma ne nécessitent pas hors ligne et ne verrouillent pas des tables ou des colonnes entières ; vous pouvez continuer l'écriture de données dans la base de données pendant la mise à jour du schéma. En savoir plus sur les compatibilités des mises à jour de schéma et des performances liées aux modifications de schéma Effectuez des mises à jour de schéma.

Ajouter une colonne

Vous pouvez ajouter une colonne sur la ligne de commande à l'aide de la Google Cloud CLI ou de manière programmatique à l'aide la bibliothèque cliente Spanner pour C++.

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 C++

Utilisez la fonction DatabaseAdminClient::UpdateDatabase() pour modifier le schéma.

void AddColumn(google::cloud::spanner_admin::DatabaseAdminClient client,
               std::string const& project_id, std::string const& instance_id,
               std::string const& database_id) {
  google::cloud::spanner::Database database(project_id, instance_id,
                                            database_id);
  auto metadata =
      client
          .UpdateDatabaseDdl(
              database.FullName(),
              {"ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"})
          .get();
  if (!metadata) throw std::move(metadata).status();
  std::cout << "Added MarketingBudget column\n";
}

Exécutez l'exemple à l'aide de la commande add-column.

bazel run //google/cloud/spanner/samples:samples -- \
    add-column $GCLOUD_PROJECT 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).

void UpdateData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto commit_result = client.Commit(spanner::Mutations{
      spanner::UpdateMutationBuilder("Albums",
                                     {"SingerId", "AlbumId", "MarketingBudget"})
          .EmplaceRow(1, 1, 100000)
          .EmplaceRow(2, 2, 500000)
          .Build()});
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << "Update was successful [spanner_update_data]\n";
}

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

bazel run //google/cloud/spanner/samples:samples -- \
    update-data $GCLOUD_PROJECT 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.

void QueryNewColumn(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  spanner::SqlStatement select(
      "SELECT SingerId, AlbumId, MarketingBudget FROM Albums");
  using RowType =
      std::tuple<std::int64_t, std::int64_t, absl::optional<std::int64_t>>;

  auto rows = client.ExecuteQuery(std::move(select));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "AlbumId: " << std::get<1>(*row) << "\t";
    auto marketing_budget = std::get<2>(*row);
    if (marketing_budget) {
      std::cout << "MarketingBudget: " << *marketing_budget << "\n";
    } else {
      std::cout << "MarketingBudget: NULL\n";
    }
  }
  std::cout << "Read completed for [spanner_read_data_with_new_column]\n";
}

Pour mettre en œuvre cette requête, exécutez l'exemple en utilisant l'argument query-new-column.

bazel run //google/cloud/spanner/samples:samples -- \
    query-new-column $GCLOUD_PROJECT test-instance example-db

Vous devriez voir les éléments suivants :

SingerId: 1 AlbumId: 1  MarketingBudget: 100000
SingerId: 1 AlbumId: 2  MarketingBudget: NULL
SingerId: 2 AlbumId: 1  MarketingBudget: NULL
SingerId: 2 AlbumId: 2  MarketingBudget: 500000
SingerId: 2 AlbumId: 3  MarketingBudget: NULL

Mettre à jour des données

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

Vous utilisez la fonction Client::ExecuteDml() pour exécuter une instruction LMD.

void DmlGettingStartedUpdate(google::cloud::spanner::Client client) {
  using ::google::cloud::StatusOr;
  namespace spanner = ::google::cloud::spanner;

  // A helper to read the budget for the given album and singer.
  auto get_budget = [&](spanner::Transaction txn, std::int64_t album_id,
                        std::int64_t singer_id) -> StatusOr<std::int64_t> {
    auto key = spanner::KeySet().AddKey(spanner::MakeKey(album_id, singer_id));
    auto rows = client.Read(std::move(txn), "Albums", key, {"MarketingBudget"});
    using RowType = std::tuple<absl::optional<std::int64_t>>;
    auto row = spanner::GetSingularRow(spanner::StreamOf<RowType>(rows));
    if (!row) return std::move(row).status();
    auto const budget = std::get<0>(*row);
    return budget ? *budget : 0;
  };

  // A helper to update the budget for the given album and singer.
  auto update_budget = [&](spanner::Transaction txn, std::int64_t album_id,
                           std::int64_t singer_id, std::int64_t budget) {
    auto sql = spanner::SqlStatement(
        "UPDATE Albums SET MarketingBudget = @AlbumBudget"
        "  WHERE SingerId = @SingerId AND AlbumId = @AlbumId",
        {{"AlbumBudget", spanner::Value(budget)},
         {"AlbumId", spanner::Value(album_id)},
         {"SingerId", spanner::Value(singer_id)}});
    return client.ExecuteDml(std::move(txn), std::move(sql));
  };

  auto const transfer_amount = 20000;
  auto commit_result = client.Commit(
      [&](spanner::Transaction const& txn) -> StatusOr<spanner::Mutations> {
        auto budget1 = get_budget(txn, 1, 1);
        if (!budget1) return std::move(budget1).status();
        if (*budget1 < transfer_amount) {
          return google::cloud::Status(
              google::cloud::StatusCode::kUnknown,
              "cannot transfer " + std::to_string(transfer_amount) +
                  " from budget of " + std::to_string(*budget1));
        }
        auto budget2 = get_budget(txn, 2, 2);
        if (!budget2) return std::move(budget2).status();
        auto update = update_budget(txn, 1, 1, *budget1 - transfer_amount);
        if (!update) return std::move(update).status();
        update = update_budget(txn, 2, 2, *budget2 + transfer_amount);
        if (!update) return std::move(update).status();
        return spanner::Mutations{};
      });
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << "Update was successful [spanner_dml_getting_started_update]\n";
}

Exécutez l'exemple en utilisant l'argument getting-started-update.

bazel run //google/cloud/spanner/samples:samples -- \
    getting-started-update $GCLOUD_PROJECT test-instance example-db

Vous devriez obtenir le résultat suivant :

Update was successful [spanner_dml_getting_started_update]

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. J'aime autres mises à jour de schéma, Spanner permet d'ajouter un index continue de diffuser du trafic. Spanner remplit automatiquement 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 Ajoutez un index secondaire.

Une fois que vous avez ajouté un index secondaire, Spanner l'utilise automatiquement pour 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 C++.

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 C++

En vous aidant de la fonction DatabaseAdminClient::UpdateDatabase(), ajoutez un index :

void AddIndex(google::cloud::spanner_admin::DatabaseAdminClient client,
              std::string const& project_id, std::string const& instance_id,
              std::string const& database_id) {
  google::cloud::spanner::Database database(project_id, instance_id,
                                            database_id);
  auto metadata =
      client
          .UpdateDatabaseDdl(
              database.FullName(),
              {"CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"})
          .get();
  if (!metadata) throw std::move(metadata).status();
  std::cout << "`AlbumsByAlbumTitle` Index successfully added, new DDL:\n"
            << metadata->DebugString();
}

Exécutez l'exemple en utilisant l'argument add-index.

bazel run //google/cloud/spanner/samples:samples -- \
    add-index $GCLOUD_PROJECT test-instance example-db

L'ajout d'un index peut prendre quelques minutes. Une fois l'index ajouté, le résultat doit ressembler à ce qui suit :

`AlbumsByAlbumTitle` Index successfully added, new DDL:
database: "projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
commit_timestamps {
  seconds: 1581011550
  nanos: 531102000
}

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, appelez la méthode Client::Read(), qui lit un nombre quelconque de lignes (zéro ou plus) dans une base de données à l'aide d'un index.

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

void ReadDataWithIndex(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  auto rows =
      client.Read("Albums", google::cloud::spanner::KeySet::All(),
                  {"AlbumId", "AlbumTitle"},
                  google::cloud::Options{}.set<spanner::ReadIndexNameOption>(
                      "AlbumsByAlbumTitle"));
  using RowType = std::tuple<std::int64_t, std::string>;
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "AlbumId: " << std::get<0>(*row) << "\t";
    std::cout << "AlbumTitle: " << std::get<1>(*row) << "\n";
  }
  std::cout << "Read completed for [spanner_read_data_with_index]\n";
}

Exécutez l'exemple en utilisant l'argument read-data-with-index.

bazel run //google/cloud/spanner/samples:samples -- \
    read-data-with-index $GCLOUD_PROJECT test-instance example-db

Vous devriez obtenir le résultat suivant :

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

Ajouter un index pour les lectures d'index uniquement

Vous avez peut-être remarqué que l'exemple de lecture précédent n'inclut pas la lecture 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 C++

Vous utilisez la fonction DatabaseAdminClient::UpdateDatabase() pour ajouter un index avec une clause STORING pour :

void AddStoringIndex(google::cloud::spanner_admin::DatabaseAdminClient client,
                     std::string const& project_id,
                     std::string const& instance_id,
                     std::string const& database_id) {
  google::cloud::spanner::Database database(project_id, instance_id,
                                            database_id);
  auto metadata = client
                      .UpdateDatabaseDdl(database.FullName(), {R"""(
                        CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle)
                            STORING (MarketingBudget))"""})
                      .get();
  if (!metadata) throw std::move(metadata).status();
  std::cout << "`AlbumsByAlbumTitle2` Index successfully added, new DDL:\n"
            << metadata->DebugString();
}

Exécutez l'exemple en utilisant l'argument add-storing-index.

bazel run //google/cloud/spanner/samples:samples -- \
    add-storing-index $GCLOUD_PROJECT test-instance example-db

Le résultat doit ressembler à ce qui suit :

`AlbumsByAlbumTitle2` Index successfully added, new DDL:
database: "projects/$GCLOUD_PROJECT/instances/test-instance/databases/example-db"
statements: "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)"
commit_timestamps {
  seconds: 1581012328
  nanos: 416682000
}

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 :

Lisez des données à l'aide de l'index de stockage que vous avez créé en exécutant une requête qui spécifie explicitement ce nouvel index :

void ReadDataWithStoringIndex(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  auto rows =
      client.Read("Albums", google::cloud::spanner::KeySet::All(),
                  {"AlbumId", "AlbumTitle", "MarketingBudget"},
                  google::cloud::Options{}.set<spanner::ReadIndexNameOption>(
                      "AlbumsByAlbumTitle2"));
  using RowType =
      std::tuple<std::int64_t, std::string, absl::optional<std::int64_t>>;
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "AlbumId: " << std::get<0>(*row) << "\t";
    std::cout << "AlbumTitle: " << std::get<1>(*row) << "\t";
    auto marketing_budget = std::get<2>(*row);
    if (marketing_budget) {
      std::cout << "MarketingBudget: " << *marketing_budget << "\n";
    } else {
      std::cout << "MarketingBudget: NULL\n";
    }
  }
  std::cout << "Read completed for [spanner_read_data_with_storing_index]\n";
}

Exécutez l'exemple en utilisant l'argument read-data-with-storing-index.

bazel run //google/cloud/spanner/samples:samples -- \
    read-data-with-storing-index $GCLOUD_PROJECT test-instance example-db

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

AlbumId: 2  AlbumTitle: Forever Hold Your Peace MarketingBudget: 520000
AlbumId: 2  AlbumTitle: Go, Go, Go  MarketingBudget: NULL
AlbumId: 1  AlbumTitle: Green   MarketingBudget: NULL
AlbumId: 3  AlbumTitle: Terrified   MarketingBudget: NULL
AlbumId: 1  AlbumTitle: Total Junk  MarketingBudget: 80000

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. Le type Transaction permet de représenter tous les genres de transactions. Utilisez la fonction de fabrique MakeReadOnlyTransaction() pour créer une transaction en lecture seule.

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

void ReadOnlyTransaction(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto read_only = spanner::MakeReadOnlyTransaction();

  spanner::SqlStatement select(
      "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;

  // Read#1.
  auto rows1 = client.ExecuteQuery(read_only, select);
  std::cout << "Read 1 results\n";
  for (auto& row : spanner::StreamOf<RowType>(rows1)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row)
              << " AlbumId: " << std::get<1>(*row)
              << " AlbumTitle: " << std::get<2>(*row) << "\n";
  }
  // Read#2. Even if changes occur in-between the reads the transaction ensures
  // that Read #1 and Read #2 return the same data.
  auto rows2 = client.ExecuteQuery(read_only, select);
  std::cout << "Read 2 results\n";
  for (auto& row : spanner::StreamOf<RowType>(rows2)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row)
              << " AlbumId: " << std::get<1>(*row)
              << " AlbumTitle: " << std::get<2>(*row) << "\n";
  }
}

Exécutez l'exemple en utilisant l'argument read-only-transaction.

bazel run //google/cloud/spanner/samples:samples -- \
    read-only-transaction $GCLOUD_PROJECT test-instance example-db

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

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

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.

Étape suivante

• Découvrez comment accéder à Spanner avec une instance de machine virtuelle.

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

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