Esta página foi traduzida pela API Cloud Translation.

Introdução ao Spanner em C++
Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Objetivos

Este tutorial orienta você nas seguintes etapas usando a biblioteca de cliente Spanner para C++:

Crie uma instância e um banco de dados do Spanner.
Escreva, leia e execute consultas SQL em dados no banco de dados.
Atualize o esquema do banco de dados.
Atualizar dados usando uma transação de leitura e gravação.
Adicione um índice secundário ao banco de dados.
Use o índice para ler e executar consultas SQL em dados.
Recupere dados usando uma transação somente leitura.

Custos

Este tutorial usa o Spanner, que é um componente faturável doGoogle Cloud. Para obter informações sobre o custo de uso do Spanner, consulte Preços .

Antes de começar

Conclua as etapas descritas em Configuração , que abrangem a criação e a configuração de um padrão Google Cloud projeto, habilitando o faturamento, habilitando a API do Cloud Spanner e configurando o OAuth 2.0 para obter credenciais de autenticação para usar a API do Cloud Spanner.

Em particular, certifique-se de executar gcloud auth application-default login para configurar seu ambiente de desenvolvimento local com credenciais de autenticação.

Nota: Se você não planeja manter os recursos criados neste tutorial, considere criar um novo Google Cloud projeto em vez de selecionar um projeto existente. Após concluir o tutorial, você pode excluir o projeto, removendo todos os recursos associados a ele.

Prepare seu ambiente C++ local

Clone o repositório do aplicativo de exemplo na sua máquina local:

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

Instale o Bazel para Linux usando estas instruções .
Mude para o diretório que contém o código de exemplo do Spanner:
```
cd $HOME/google-cloud-cpp
```

Crie os exemplos com este comando:

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

Configure a autenticação e a autorização para o projeto google-cloud-cpp .
```
gcloud auth application-default login
```
Crie uma variável de ambiente chamada GCLOUD_PROJECT . Substitua [MY_PROJECT_ID] pelo seu Google Cloud ID do projeto. Você pode encontrar esse ID na página de boas-vindas do seu projeto.
```
export GCLOUD_PROJECT=[MY_PROJECT_ID]
```

Criar uma instância

Ao usar o Spanner pela primeira vez, você precisa criar uma instância, que é uma alocação de recursos usados pelos bancos de dados do Spanner. Ao criar uma instância, você escolhe uma configuração de instância , que determina onde seus dados serão armazenados, e também o número de nós a serem usados, que determina a quantidade de recursos de serviço e armazenamento na sua instância.

Execute o seguinte comando para criar uma instância do Spanner na região us-central1 com 1 nó:

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

Observe que isso cria uma instância com as seguintes características:

ID da instância test-instance
Nome de exibição Test Instance
Configuração de instância regional-us-central1 (Configurações regionais armazenam dados em uma região, enquanto configurações multirregionais distribuem dados entre várias regiões. Para obter mais informações, consulte Sobre instâncias .)
Contagem de nós de 1 ( node_count corresponde à quantidade de recursos de serviço e armazenamento disponíveis para bancos de dados na instância. Saiba mais em Nós e unidades de processamento .)

Você deverá ver:

Creating instance...done.

Veja os arquivos de amostra

O repositório de exemplos contém um exemplo que mostra como usar o Spanner com C++.

Dê uma olhada no arquivo google/cloud/spanner/samples/samples.cc , que mostra como criar um banco de dados e modificar um esquema de banco de dados. Os dados usam o esquema de exemplo mostrado na página Esquema e modelo de dados .

Criar um banco de dados

GoogleSQL

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

PostgreSQL

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

bazel run //google/cloud/spanner/samples:postgresql_samples -- \
      interleaved-table $GCLOUD_PROJECT test-instance example-db

Você deverá ver:

Created database [projects/${GCLOUD_PROJECT}/instances/test-instance/databases/example-db]

O código a seguir cria um banco de dados e duas tabelas no banco de dados.

GoogleSQL

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

PostgreSQL

No dialeto PostgreSQL, o banco de dados precisa ser criado antes de enviar uma solicitação DDL para criar uma tabela.

O exemplo a seguir cria um banco de dados:

void CreateDatabase(google::cloud::spanner_admin::DatabaseAdminClient client,
                    google::cloud::spanner::Database const& database) {
  google::spanner::admin::database::v1::CreateDatabaseRequest request;
  request.set_parent(database.instance().FullName());
  request.set_create_statement("CREATE DATABASE \"" + database.database_id() +
                               "\"");
  request.set_database_dialect(
      google::spanner::admin::database::v1::DatabaseDialect::POSTGRESQL);
  auto db = client.CreateDatabase(request).get();
  if (!db) throw std::move(db).status();
  std::cout << "Database " << db->name() << " created.\n";
}

O exemplo a seguir cria as duas tabelas no banco de dados:

void InterleavedTable(google::cloud::spanner_admin::DatabaseAdminClient client,
                      google::cloud::spanner::Database const& database) {
  // The Spanner PostgreSQL dialect extends the PostgreSQL dialect with
  // certain Spanner specific features, such as interleaved tables. See
  // https://cloud.google.com/spanner/docs/postgresql/data-definition-language#create_table
  // for the full CREATE TABLE syntax.
  std::vector<std::string> statements = {
      R"""(
        CREATE TABLE Singers (
            SingerId        BIGINT NOT NULL,
            FirstName       CHARACTER VARYING(1024) NOT NULL,
            LastName        CHARACTER VARYING(1024) NOT NULL,
            PRIMARY KEY(SingerId)
        )
      )""",
      R"""(
        CREATE TABLE Albums (
            SingerId        BIGINT NOT NULL,
            AlbumId         BIGINT NOT NULL,
            AlbumTitle      CHARACTER VARYING NOT NULL,
            MarketingBudget BIGINT,
            PRIMARY KEY(SingerId, AlbumId)
        ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE
      )""",
  };
  auto metadata =
      client.UpdateDatabaseDdl(database.FullName(), statements).get();
  google::cloud::spanner_testing::LogUpdateDatabaseDdl(  //! TODO(#4758)
      client, database, metadata.status());              //! TODO(#4758)
  if (!metadata) throw std::move(metadata).status();
  std::cout << "Tables created.\nNew DDL:\n" << metadata->DebugString();
}

O próximo passo é gravar dados no seu banco de dados.

Criar um cliente de banco de dados

Antes de poder fazer leituras ou gravações, você deve criar um Client :

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

Um Client permite ler, escrever, consultar e executar transações em um banco de dados Spanner. Normalmente, você cria um Client quando seu aplicativo é inicializado e, em seguida, reutiliza esse Client para ler, escrever e executar transações. Cada cliente utiliza recursos do Spanner. O destruidor do Client limpará automaticamente os recursos Client , incluindo as conexões de rede.

Leia mais sobre Client no Google Cloud Referência do Spanner C++ .

Escrever dados com DML

Você pode inserir dados usando Linguagem de Manipulação de Dados (DML) em uma transação de leitura e gravação.

Use a função Client::ExecuteDml() para executar uma instrução DML.

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

Execute o exemplo usando o argumento getting-started-insert .

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

Você deverá ver:

Insert was successful [spanner_dml_getting_started_insert]

Escrever dados com mutações

Você também pode inserir dados usando mutações .

Você grava dados usando um objeto Client . A função Client::Commit() cria e confirma uma transação para gravações que são executadas atomicamente em um único ponto lógico no tempo em colunas, linhas e tabelas em um banco de dados.

Este código mostra como escrever os dados usando mutações:

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

Execute o exemplo usando o argumento insert-data .

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

Você deverá ver:

Insert was successful [spanner_insert_data]

Consultar dados usando SQL

O Spanner oferece suporte a uma interface SQL para leitura de dados, que você pode acessar na linha de comando usando o Google Cloud CLI ou programaticamente usando a biblioteca de cliente Spanner para C++.

Na linha de comando

Execute a seguinte instrução SQL para ler os valores de todas as colunas da tabela Albums :

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

O resultado deve ser:

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

Use a biblioteca cliente Spanner para C++

Além de executar uma instrução SQL na linha de comando, você pode emitir a mesma instrução SQL programaticamente usando a biblioteca de cliente Spanner para C++.

Use a função Client::ExecuteQuery() para executar a consulta SQL. Veja como emitir a consulta e acessar os dados:

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

Execute o exemplo usando o argumento query_data .

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

Você deverá ver o seguinte resultado:

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

Consulta usando um parâmetro SQL

Se o seu aplicativo tiver uma consulta executada com frequência, você pode melhorar seu desempenho parametrizando-a. A consulta paramétrica resultante pode ser armazenada em cache e reutilizada, o que reduz os custos de compilação. Para obter mais informações, consulte Usar parâmetros de consulta para acelerar consultas executadas com frequência .

Aqui está um exemplo de uso de um parâmetro na cláusula WHERE para consultar registros que contêm um valor específico para 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";
}

Execute o exemplo usando o comando query-with-parameter.

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

Você deverá ver o seguinte resultado:

SingerId: 12    FirstName: Melissa      LastName: Garcia

Ler dados usando a API de leitura

Além da interface SQL do Spanner, o Spanner também suporta uma interface de leitura.

Use a função Client::Read() para ler linhas do banco de dados. Use um objeto KeySet para definir uma coleção de chaves e intervalos de chaves para leitura.

Veja como ler os dados:

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

Execute o exemplo usando o argumento read-data .

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

Você deverá ver uma saída semelhante a:

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

Atualizar o esquema do banco de dados

Suponha que você precise adicionar uma nova coluna chamada MarketingBudget à tabela Albums . Adicionar uma nova coluna a uma tabela existente requer uma atualização do esquema do seu banco de dados. O Spanner suporta atualizações de esquema em um banco de dados enquanto este continua a servir tráfego. As atualizações de esquema não exigem que o banco de dados fique offline e não bloqueiam tabelas ou colunas inteiras; você pode continuar gravando dados no banco de dados durante a atualização do esquema. Saiba mais sobre as atualizações de esquema suportadas e o desempenho das alterações de esquema em Fazer atualizações de esquema .

Adicionar uma coluna

Você pode adicionar uma coluna na linha de comando usando o Google Cloud CLI ou programaticamente usando a biblioteca de cliente Spanner para C++.

Na linha de comando

Use o seguinte comando ALTER TABLE para adicionar a nova coluna à tabela:

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'

Você deverá ver:

Schema updating...done.

Use a biblioteca cliente Spanner para C++

Use a função DatabaseAdminClient::UpdateDatabase() para modificar o esquema.

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

Execute o exemplo usando o comando add-column .

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

Você deverá ver:

Added MarketingBudget column

Grave dados na nova coluna

O código a seguir grava dados na nova coluna. Ele define MarketingBudget como 100000 para a linha indexada por Albums(1, 1) e como 500000 para a linha indexada por 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";
}

Execute o exemplo usando o argumento update-data .

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

Você também pode executar uma consulta SQL ou uma chamada de leitura para buscar os valores que acabou de escrever.

Aqui está o código para executar a consulta:

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

Para executar esta consulta, execute o exemplo usando o argumento query-new-column .

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

Você deverá ver:

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

Atualizar dados

Você pode atualizar dados usando DML em uma transação de leitura e gravação.

Use a função Client::ExecuteDml() para executar uma instrução DML.

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

Execute o exemplo usando o argumento getting-started-update .

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

Você deverá ver:

Update was successful [spanner_dml_getting_started_update]

Use um índice secundário

Suponha que você queira buscar todas as linhas de Albums que possuem valores AlbumTitle em um determinado intervalo. Você poderia ler todos os valores da coluna AlbumTitle usando uma instrução SQL ou uma chamada de leitura e, em seguida, descartar as linhas que não atendem aos critérios, mas realizar essa varredura completa da tabela é caro, especialmente para tabelas com muitas linhas. Em vez disso, você pode acelerar a recuperação de linhas ao pesquisar por colunas que não sejam de chave primária criando um índice secundário na tabela.

Adicionar um índice secundário a uma tabela existente requer uma atualização de esquema. Assim como outras atualizações de esquema, o Spanner permite a adição de um índice enquanto o banco de dados continua a servir tráfego. O Spanner preenche automaticamente o índice com os dados existentes. Os preenchimentos podem levar alguns minutos para serem concluídos, mas você não precisa desconectar o banco de dados nem evitar gravar na tabela indexada durante esse processo. Para obter mais detalhes, consulte Adicionar um índice secundário .

Após adicionar um índice secundário, o Spanner o utiliza automaticamente para consultas SQL que provavelmente serão executadas mais rapidamente com o índice. Se você usar a interface de leitura, deverá especificar o índice que deseja usar.

Adicionar um índice secundário

Você pode adicionar um índice na linha de comando usando o gcloud CLI ou programaticamente usando a biblioteca de cliente Spanner para C++.

Na linha de comando

Use o seguinte comando CREATE INDEX para adicionar um índice ao banco de dados:

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

Você deverá ver:

Schema updating...done.

Usando a biblioteca cliente Spanner para C++

Use a função DatabaseAdminClient::UpdateDatabase() para adicionar um índice:

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

Execute o exemplo usando o argumento add-index .

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

Adicionar um índice pode levar alguns minutos. Após adicioná-lo, você deverá ver uma saída semelhante a esta:

`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
}

Leia usando o índice

Para consultas SQL, o Spanner usa automaticamente um índice apropriado. Na interface de leitura, você deve especificar o índice na sua solicitação.

Para usar o índice na interface de leitura, use a função Client::Read() , que lê zero ou mais linhas de um banco de dados usando um índice.

O código a seguir busca todas as colunas AlbumId e AlbumTitle do índice 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";
}

Execute o exemplo usando o argumento read-data-with-index .

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

Você deverá ver:

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

Adicionar um índice para leituras somente de índice

Você deve ter notado que o exemplo de leitura anterior não inclui a leitura da coluna MarketingBudget . Isso ocorre porque a interface de leitura do Spanner não suporta a capacidade de unir um índice a uma tabela de dados para pesquisar valores que não estão armazenados no índice.

Crie uma definição alternativa de AlbumsByAlbumTitle que armazene uma cópia de MarketingBudget no índice.

Na linha de comando

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)

Adicionar um índice pode levar alguns minutos. Após adicioná-lo, você deverá ver:

Schema updating...done.

Usando a biblioteca cliente Spanner para C++

Use a função DatabaseAdminClient::UpdateDatabase() para adicionar um índice com uma cláusula STORING para:

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

Execute o exemplo usando o argumento add-storing-index .

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

Você deverá ver uma saída semelhante a esta:

`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
}

Agora você pode executar uma leitura que busca todas as colunas AlbumId , AlbumTitle e MarketingBudget do índice AlbumsByAlbumTitle2 :

Leia os dados usando o índice de armazenamento que você criou executando uma consulta que especifica explicitamente o índice:

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

Execute o exemplo usando o argumento read-data-with-storing-index .

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

Você deverá ver uma saída semelhante a:

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

Recuperar dados usando transações somente leitura

Suponha que você queira executar mais de uma leitura no mesmo registro de data e hora. Transações somente leitura observam um prefixo consistente do histórico de confirmações da transação, de modo que seu aplicativo sempre obtém dados consistentes. O tipo Transaction é usado para representar todos os tipos de transações. Use a função de fábrica MakeReadOnlyTransaction() para criar uma transação somente leitura.

A seguir, é mostrado como executar uma consulta e realizar uma leitura na mesma transação somente leitura:

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

Execute o exemplo usando o argumento read-only-transaction .

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

Você deverá ver uma saída semelhante a:

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

Limpar

Para evitar cobranças adicionais na sua conta do Cloud Billing pelos recursos usados neste tutorial, elimine o banco de dados e exclua a instância que você criou.

Excluir o banco de dados

Se você excluir uma instância, todos os bancos de dados contidos nela serão excluídos automaticamente. Esta etapa mostra como excluir um banco de dados sem excluir uma instância (você ainda incorrerá em cobranças pela instância).

Na linha de comando

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

Usando o Google Cloud console

Vá para a página Instâncias do Spanner no Google Cloud console.
Vá para a página Instâncias
Clique na instância.
Clique no banco de dados que você deseja excluir.
Na página Detalhes do banco de dados , clique em Excluir .
Confirme que deseja excluir o banco de dados e clique em Excluir .

Excluir a instância

A exclusão de uma instância remove automaticamente todos os bancos de dados criados nela.

Na linha de comando

gcloud spanner instances delete test-instance

Usando o Google Cloud console

Vá para a página Instâncias do Spanner no Google Cloud console.
Vá para a página Instâncias
Clique na sua instância.
Clique em Excluir .
Confirme que deseja excluir a instância e clique em Excluir .

O que vem a seguir

Aprenda como acessar o Spanner com uma instância de máquina virtual .
Saiba mais sobre credenciais de autorização e autenticação em Autenticar em serviços de nuvem usando bibliotecas de cliente .
Saiba mais sobre as práticas recomendadas de design do Spanner Schema .

Introdução ao Spanner em C++ Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Objetivos

Custos

Antes de começar

Limpar

Excluir o banco de dados

Na linha de comando

Usando o Google Cloud console

Excluir a instância

Na linha de comando

Usando o Google Cloud console

O que vem a seguir

Introdução ao Spanner em C++
Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.