Esta página se ha traducido con Cloud Translation API.

Introducción a Spanner en C++
Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Objetivos

Este tutorial lo guiará a través de los siguientes pasos utilizando la biblioteca cliente Spanner para C++:

Cree una instancia y una base de datos de Spanner.
Escribir, leer y ejecutar consultas SQL sobre datos de la base de datos.
Actualizar el esquema de la base de datos.
Actualizar datos mediante una transacción de lectura y escritura.
Agregar un índice secundario a la base de datos.
Utilice el índice para leer y ejecutar consultas SQL sobre los datos.
Recupere datos mediante una transacción de solo lectura.

Costos

Este tutorial utiliza Spanner, que es un componente facturable deGoogle CloudPara obtener información sobre el costo de usar Spanner, consulte Precios .

Antes de empezar

Complete los pasos descritos en Configuración , que cubren la creación y configuración de un valor predeterminado. Google Cloud proyecto, habilitar la facturación, habilitar la API de Cloud Spanner y configurar OAuth 2.0 para obtener credenciales de autenticación para usar la API de Cloud Spanner.

En particular, asegúrese de ejecutar gcloud auth application-default login para configurar su entorno de desarrollo local con credenciales de autenticación.

Nota: Si no planea conservar los recursos que cree en este tutorial, considere crear uno nuevo. Google Cloud proyecto en lugar de seleccionar uno existente. Tras finalizar el tutorial, puede eliminar el proyecto y así eliminar todos los recursos asociados.

Prepare su entorno C++ local

Clone el repositorio de aplicaciones de muestra en su máquina local:

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

Instale Bazel para Linux siguiendo estas instrucciones .
Cambie al directorio que contiene el código de muestra de Spanner:
```
cd $HOME/google-cloud-cpp
```

Construya las muestras con este comando:

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

Configurar la autenticación y la autorización para el proyecto google-cloud-cpp .
```
gcloud auth application-default login
```
Cree una variable de entorno llamada GCLOUD_PROJECT . Reemplace [MY_PROJECT_ID] con su Google Cloud ID del proyecto. Puede encontrarlo en la página de bienvenida de su proyecto.
```
export GCLOUD_PROJECT=[MY_PROJECT_ID]
```

Crear una instancia

Al usar Spanner por primera vez, debe crear una instancia, que consiste en una asignación de recursos que utilizan las bases de datos de Spanner. Al crear una instancia, se elige una configuración que determina dónde se almacenan los datos y el número de nodos a usar, lo que determina la cantidad de recursos de servicio y almacenamiento en la instancia.

Ejecute el siguiente comando para crear una instancia de Spanner en la región us-central1 con 1 nodo:

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

Tenga en cuenta que esto crea una instancia con las siguientes características:

ID de instancia test-instance
Nombre para mostrar Test Instance
Configuración de instancia regional-us-central1 (las configuraciones regionales almacenan datos en una región, mientras que las configuraciones multirregionales distribuyen datos entre varias regiones. Para obtener más información, consulte Acerca de las instancias ).
Cantidad de nodos de 1 ( node_count corresponde a la cantidad de recursos de servicio y almacenamiento disponibles para las bases de datos en la instancia. Obtenga más información en Nodos y unidades de procesamiento ).

Deberías ver:

Creating instance...done.

Mirar archivos de muestra

El repositorio de muestras contiene un ejemplo que muestra cómo utilizar Spanner con C++.

Consulte el archivo google/cloud/spanner/samples/samples.cc , que muestra cómo crear una base de datos y modificar su esquema. Los datos utilizan el esquema de ejemplo que se muestra en la página Esquema y modelo de datos .

Crear una base de datos

Google SQL

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

Deberías ver:

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

El siguiente código crea una base de datos y dos tablas en la base de datos.

Google SQL

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

En el dialecto PostgreSQL, la base de datos debe crearse antes de enviar una solicitud DDL para crear una tabla.

El siguiente ejemplo crea una base de datos:

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

El siguiente ejemplo crea las dos tablas en la base de datos:

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

El siguiente paso es escribir datos en su base de datos.

Crear un cliente de base de datos

Antes de poder realizar lecturas o escrituras, debe crear un Client :

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

Un Client permite leer, escribir, consultar y ejecutar transacciones en una base de datos Spanner. Normalmente, se crea un Client al iniciar la aplicación y luego se reutiliza para leer, escribir y ejecutar Client . Cada cliente utiliza recursos de Spanner. El destructor de Client borrará automáticamente los recursos Client , incluidas las conexiones de red.

Lea más sobre Client en el Google Cloud Referencia de C++ de Spanner .

Escribir datos con DML

Puede insertar datos utilizando el lenguaje de manipulación de datos (DML) en una transacción de lectura y escritura.

Utilice la función Client::ExecuteDml() para ejecutar una declaración 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";
}

Ejecute el ejemplo utilizando el argumento getting-started-insert .

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

Deberías ver:

Insert was successful [spanner_dml_getting_started_insert]

Escribir datos con mutaciones

También puedes insertar datos usando mutaciones .

Se escriben datos mediante un objeto Client . La función Client::Commit() crea y confirma una transacción para escrituras que se ejecutan de forma automática en un único punto lógico en el tiempo, en columnas, filas y tablas de una base de datos.

Este código muestra cómo escribir los datos usando mutaciones:

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

Ejecute la muestra utilizando el argumento insert-data .

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

Deberías ver:

Insert was successful [spanner_insert_data]

Consultar datos mediante SQL

Spanner admite una interfaz SQL para leer datos, a la que puedes acceder en la línea de comandos mediante la CLI de Google Cloud o mediante programación mediante la biblioteca cliente Spanner para C++.

En la línea de comandos

Ejecute la siguiente declaración SQL para leer los valores de todas las columnas de la tabla Albums :

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

El resultado debería 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

Utilice la biblioteca cliente Spanner para C++

Además de ejecutar una declaración SQL en la línea de comandos, puede emitir la misma declaración SQL mediante programación utilizando la biblioteca cliente Spanner para C++.

Se utiliza la función Client::ExecuteQuery() para ejecutar la consulta SQL. A continuación, se explica cómo ejecutar la consulta y acceder a los datos:

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

Ejecute la muestra utilizando el argumento query_data .

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

Deberías ver el siguiente 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 utilizando un parámetro SQL

Si su aplicación tiene una consulta que se ejecuta con frecuencia, puede mejorar su rendimiento parametrizándola. La consulta paramétrica resultante puede almacenarse en caché y reutilizarse, lo que reduce los costos de compilación. Para obtener más información, consulte Usar parámetros de consulta para acelerar las consultas que se ejecutan con frecuencia .

A continuación se muestra un ejemplo del uso de un parámetro en la cláusula WHERE para consultar registros que contienen un 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";
}

Ejecute la muestra utilizando el comando query-with-parameter.

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

Deberías ver el siguiente resultado:

SingerId: 12    FirstName: Melissa      LastName: Garcia

Leer datos usando la API de lectura

Además de la interfaz SQL de Spanner, Spanner también admite una interfaz de lectura.

Utilice la función Client::Read() para leer filas de la base de datos. Utilice un objeto KeySet para definir una colección de claves y rangos de claves para leer.

Aquí se explica cómo leer los datos:

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

Ejecute la muestra utilizando el argumento read-data .

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

Debería ver un resultado similar a este:

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

Actualizar el esquema de la base de datos

Supongamos que necesita agregar una nueva columna llamada MarketingBudget a la tabla Albums . Agregar una nueva columna a una tabla existente requiere actualizar el esquema de su base de datos. Spanner admite actualizaciones de esquema en una base de datos mientras esta continúa gestionando el tráfico. Las actualizaciones de esquema no requieren desconectar la base de datos ni bloquean tablas o columnas completas; puede seguir escribiendo datos en la base de datos durante la actualización del esquema. Obtenga más información sobre las actualizaciones de esquema admitidas y el rendimiento de los cambios de esquema en Realizar actualizaciones de esquema .

Agregar una columna

Puede agregar una columna en la línea de comando mediante la CLI de Google Cloud o mediante programación utilizando la biblioteca cliente Spanner para C++.

En la línea de comandos

Utilice el siguiente comando ALTER TABLE para agregar la nueva columna a la tabla:

Google SQL

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'

Deberías ver:

Schema updating...done.

Utilice la biblioteca cliente Spanner para C++

Utilice la función DatabaseAdminClient::UpdateDatabase() para modificar el 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";
}

Ejecute la muestra utilizando el comando add-column .

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

Deberías ver:

Added MarketingBudget column

Escribir datos en la nueva columna

El siguiente código escribe datos en la nueva columna. Establece MarketingBudget en 100000 para la fila especificada por Albums(1, 1) y en 500000 para la fila especificada 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";
}

Ejecute la muestra utilizando el argumento update-data .

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

También puede ejecutar una consulta SQL o una llamada de lectura para obtener los valores que acaba de escribir.

Aquí está el código para ejecutar la 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 ejecutar esta consulta, ejecute el ejemplo utilizando el argumento query-new-column .

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

Deberías 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

Actualizar datos

Puede actualizar datos utilizando DML en una transacción de lectura y escritura.

Utilice la función Client::ExecuteDml() para ejecutar una declaración 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";
}

Ejecute el ejemplo utilizando el argumento getting-started-update .

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

Deberías ver:

Update was successful [spanner_dml_getting_started_update]

Utilice un índice secundario

Supongamos que desea obtener todas las filas de Albums con valores AlbumTitle dentro de un rango determinado. Podría leer todos los valores de la columna AlbumTitle mediante una sentencia SQL o una llamada de lectura y luego descartar las filas que no cumplan los criterios. Sin embargo, realizar este análisis completo de la tabla es costoso, especialmente en tablas con muchas filas. En su lugar, puede acelerar la recuperación de filas al buscar por columnas que no sean de clave principal creando un índice secundario en la tabla.

Añadir un índice secundario a una tabla existente requiere una actualización del esquema. Al igual que otras actualizaciones de esquema, Spanner permite añadir un índice mientras la base de datos sigue gestionando el tráfico. Spanner rellena automáticamente el índice con los datos existentes. El proceso de rellenado puede tardar unos minutos, pero no es necesario desconectar la base de datos ni evitar escribir en la tabla indexada durante el proceso. Para más información, consulte "Añadir un índice secundario" .

Tras agregar un índice secundario, Spanner lo usa automáticamente para las consultas SQL que probablemente se ejecuten más rápido con él. Si usa la interfaz de lectura, debe especificar el índice que desea usar.

Agregar un índice secundario

Puede agregar un índice en la línea de comando usando la CLI de gcloud o programáticamente usando la biblioteca cliente Spanner para C++.

En la línea de comandos

Utilice el siguiente comando CREATE INDEX para agregar un índice a la base de datos:

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

Deberías ver:

Schema updating...done.

Uso de la biblioteca cliente Spanner para C++

Utilice la función DatabaseAdminClient::UpdateDatabase() para agregar un í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();
}

Ejecute la muestra utilizando el argumento add-index .

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

Añadir un índice puede tardar unos minutos. Una vez añadido, debería ver un resultado similar a este:

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

Leer utilizando el índice

Para las consultas SQL, Spanner utiliza automáticamente un índice apropiado. En la interfaz de lectura, debe especificar el índice en su solicitud.

Para utilizar el índice en la interfaz de lectura, utilice la función Client::Read() , que lee cero o más filas de una base de datos utilizando un índice.

El siguiente código obtiene todas las columnas AlbumId y AlbumTitle del í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";
}

Ejecute la muestra utilizando el argumento read-data-with-index .

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

Deberías 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

Agregar un índice para lecturas de solo índice

Quizás haya notado que el ejemplo de lectura anterior no incluye la lectura de la columna MarketingBudget . Esto se debe a que la interfaz de lectura de Spanner no permite unir un índice con una tabla de datos para buscar valores que no están almacenados en el índice.

Cree una definición alternativa de AlbumsByAlbumTitle que almacene una copia de MarketingBudget en el índice.

En la línea de comandos

Google SQL

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)

Añadir un índice puede tardar unos minutos. Una vez añadido, debería ver lo siguiente:

Schema updating...done.

Uso de la biblioteca cliente Spanner para C++

Utilice la función DatabaseAdminClient::UpdateDatabase() para agregar un índice con una 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();
}

Ejecute la muestra utilizando el argumento add-storing-index .

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

Debería ver un resultado similar a este:

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

Ahora puede ejecutar una lectura que obtenga todas las columnas AlbumId , AlbumTitle y MarketingBudget del índice AlbumsByAlbumTitle2 :

Lea los datos utilizando el índice de almacenamiento que creó ejecutando una consulta que especifique explícitamente el í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";
}

Ejecute la muestra utilizando el argumento read-data-with-storing-index .

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

Debería ver un resultado similar a este:

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 datos mediante transacciones de solo lectura

Supongamos que desea ejecutar más de una lectura en la misma marca de tiempo. Las transacciones de solo lectura siguen un prefijo consistente del historial de confirmación de transacciones, por lo que su aplicación siempre obtiene datos consistentes. El tipo Transaction se utiliza para representar todo tipo de transacciones. Utilice la función de fábrica MakeReadOnlyTransaction() para crear una transacción de solo lectura.

A continuación se muestra cómo ejecutar una consulta y realizar una lectura en la misma transacción de solo lectura:

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

Ejecute la muestra utilizando el argumento read-only-transaction .

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

Debería ver un resultado similar a este:

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

Limpieza

Para evitar incurrir en cargos adicionales en su cuenta de facturación de Cloud por los recursos utilizados en este tutorial, elimine la base de datos y borre la instancia que creó.

Eliminar la base de datos

Si elimina una instancia, todas sus bases de datos se eliminan automáticamente. Este paso muestra cómo eliminar una base de datos sin eliminar una instancia (aunque se le cobrarán cargos por la instancia).

En la línea de comandos

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

Usando el Google Cloud consola

Vaya a la página Instancias de Spanner en el Google Cloud consola.
Ir a la página de Instancias
Haga clic en la instancia.
Haga clic en la base de datos que desea eliminar.
En la página de detalles de la base de datos , haga clic en Eliminar .
Confirme que desea eliminar la base de datos y haga clic en Eliminar .

Eliminar la instancia

Al eliminar una instancia se eliminan automáticamente todas las bases de datos creadas en esa instancia.

En la línea de comandos

gcloud spanner instances delete test-instance

Usando el Google Cloud consola

Vaya a la página Instancias de Spanner en el Google Cloud consola.
Ir a la página de Instancias
Haga clic en su instancia.
Haga clic en Eliminar .
Confirme que desea eliminar la instancia y haga clic en Eliminar .

¿Qué sigue?

Aprenda cómo acceder a Spanner con una instancia de máquina virtual .
Obtenga información sobre las credenciales de autorización y autenticación en Autenticarse en servicios en la nube mediante bibliotecas de cliente .
Obtenga más información sobre las mejores prácticas de diseño de esquemas Spanner.

Introducción a Spanner en C++ Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Objetivos

Costos

Antes de empezar

Limpieza

Eliminar la base de datos

En la línea de comandos

Usando el Google Cloud consola

Eliminar la instancia

En la línea de comandos

Usando el Google Cloud consola

¿Qué sigue?

Introducción a Spanner en C++
Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.