Comienza a usar Spanner en Ruby

---

Nota sobre la interfaz de PostgreSQL: Los ejemplos de este tema están destinados a las bases de datos del dialecto GoogleSQL.

Objetivos

En este instructivo, se explican los siguientes pasos para usar Spanner para Ruby:

• Crea una base de datos y una instancia de Spanner.
• Escribe, lee y ejecuta consultas de SQL sobre datos en la base de datos.
• Actualiza el esquema de la base de datos.
• Actualiza los datos mediante una transacción de lectura y escritura.
• Agrega un índice secundario a la base de datos.
• Usa el índice para leer y ejecutar consultas de SQL sobre datos.
• Recupera datos con una transacción de solo lectura.

Costos

En este instructivo, se usa Spanner, que es un componente facturable del en Google Cloud. Para obtener información sobre el costo de usar Spanner, consulta Precios.

Antes de comenzar

Completa los pasos descritos en Configuración, que abarcan la creación y configuración de un proyecto de Google Cloud predeterminado, la facturación, la habilitación de la API de Cloud Spanner y la configuración de OAuth 2.0 para obtener credenciales de autenticación para usar la API de Cloud Spanner.

En especial, asegúrate de ejecutar gcloud auth application-default login para configurar tu entorno de desarrollo local con credenciales de autenticación.

Nota: Si no planeas conservar los recursos que creaste en este instructivo, considera crear un proyecto nuevo de Google Cloud en lugar de seleccionar uno existente. Cuando termines el instructivo, puedes borrar el proyecto y quitar todos los recursos asociados con él.

Prepara tu entorno local de Ruby

1. Instala los siguientes componentes en tu máquina de desarrollo si aún no se instalaron:

   • Ruby
   • Bundler

2. Clona el repositorio de la app de muestra en tu máquina local:

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

   De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.

3. Ve al directorio que contiene el código de muestra de Spanner:

   cd ruby-docs-samples/spanner/
   

4. Instala las dependencias:

   bundle install
   

5. Configura la variable de entorno GOOGLE_CLOUD_PROJECT en tu cuenta de Google Cloud. ID del proyecto:

   export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]
   

Crea una instancia

Cuando usas Spanner por primera vez, debes crear una instancia, que es una asignación de recursos que usan las bases de datos de Spanner. Cuando creas una instancia, debes elegir una configuración de instancia, que determina dónde se almacenan tus datos y también la cantidad de nodos que se usarán, lo que, a su vez, determina la cantidad de recursos de entrega y almacenamiento de tu instancia.

Ejecuta 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

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

• ID de instancia: test-instance
• Nombre visible: Test Instance
• Configuración de la instancia: regional-us-central1 (la configuración regional almacena datos en una región, mientras que la multirregional distribuye datos en varias regiones; Para obtener más información, consulta Acerca de las instancias.
• Recuento de nodos: 1 (node_count corresponde a la cantidad de recursos de procesamiento y almacenamiento disponibles para las bases de datos de la instancia; Obtén más información en Nodos y unidades de procesamiento de datos).

Deberías ver lo siguiente:

Creating instance...done.

Examina archivos de muestra

El repositorio de muestras contiene una muestra en la que se indica cómo usar Spanner con Ruby.

Consulta el archivo spanner_samples.rb, en el que se muestra cómo usar Spanner. El código es un instructivo sobre cómo crear y usar una base de datos nueva. Los datos utilizan el esquema de ejemplo de la página Esquema y modelo de datos.

Crea una base de datos

Para crear una base de datos llamada example-db en la instancia test-instance, ejecuta lo siguiente en la línea de comandos:

bundle exec ruby spanner_samples.rb create_database test-instance example-db

Deberías ver lo siguiente:

Created database example-db on instance test-instance

Con el siguiente código, se crea una base de datos y dos tablas en ella.

Nota: En los siguientes ejemplos de código, se usan estas dos tablas. Si no ejecutas este código, crea las tablas con la consola de Google Cloud o la CLI de gcloud. Para obtener más información, consulta el esquema de ejemplo.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

instance_path = database_admin_client.instance_path project: project_id, instance: instance_id

job = database_admin_client.create_database parent: instance_path,
                                            create_statement: "CREATE DATABASE `#{database_id}`",
                                            extra_statements: [
                                              "CREATE TABLE Singers (
      SingerId     INT64 NOT NULL,
      FirstName    STRING(1024),
      LastName     STRING(1024),
      SingerInfo   BYTES(MAX)
    ) PRIMARY KEY (SingerId)",

                                              "CREATE TABLE Albums (
      SingerId     INT64 NOT NULL,
      AlbumId      INT64 NOT NULL,
      AlbumTitle   STRING(MAX)
    ) PRIMARY KEY (SingerId, AlbumId),
    INTERLEAVE IN PARENT Singers ON DELETE CASCADE"
                                            ]

puts "Waiting for create database operation to complete"

job.wait_until_done!

puts "Created database #{database_id} on instance #{instance_id}"

El siguiente paso consiste en escribir datos en tu base de datos.

Crea un cliente de base de datos

Para realizar operaciones de lectura o escritura, debes crear un Client. Un Client es como una conexión a una base de datos, es decir, todas las interacciones con Spanner deben realizarse mediante un Client. Por lo general, creas un Client cuando se inicia la aplicación y, luego, vuelves a usar ese Client para leer, escribir y ejecutar transacciones. En el siguiente código, se muestra cómo crear un cliente.

# Imports the Google Cloud client library
require "google/cloud/spanner"

# Your Google Cloud Platform project ID
project_id = "YOUR_PROJECT_ID"

# Instantiates a client
spanner = Google::Cloud::Spanner.new project: project_id

# Your Cloud Spanner instance ID
instance_id = "my-instance"

# Your Cloud Spanner database ID
database_id = "my-database"

# Gets a reference to a Cloud Spanner instance database
database_client = spanner.client instance_id, database_id

# Execute a simple SQL statement
results = database_client.execute_query "SELECT 1"
results.rows.each do |row|
  puts row
end

Obtén más información en la referencia de Client.

Escribe datos con DML

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

Usa el método execute_update() para ejecutar una declaración DML.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id
row_count = 0

client.transaction do |transaction|
  row_count = transaction.execute_update(
    "INSERT INTO Singers (SingerId, FirstName, LastName) VALUES
     (12, 'Melissa', 'Garcia'),
     (13, 'Russell', 'Morales'),
     (14, 'Jacqueline', 'Long'),
     (15, 'Dylan', 'Shaw'),
     (16, 'Billie', 'Eillish'),
     (17, 'Judy', 'Garland'),
     (18, 'Taylor', 'Swift'),
     (19, 'Miley', 'Cyrus'),
     (20, 'Michael', 'Jackson'),
     (21, 'Ariana', 'Grande'),
     (22, 'Elvis', 'Presley'),
     (23, 'Kanye', 'West'),
     (24, 'Lady', 'Gaga'),
     (25, 'Nick', 'Jonas')"
  )
end

puts "#{row_count} records inserted."

Ejecuta la muestra con el argumento write_using_dml.

bundle exec ruby spanner_samples.rb write_using_dml test-instance example-db

Deberías ver lo siguiente:

 4 records inserted.

Nota: Existen límites para el tamaño de confirmación. Consulta el límite de CRUD para obtener más información.

Escribe datos con mutaciones

También puedes insertar datos mediante mutaciones.

Escribirás datos con un objeto Client. El método Client#commit crea y confirma una transacción para escrituras que se ejecutan de forma atómica en un único momento lógico a través de las columnas, las filas y las tablas en una base de datos.

En este código, se muestra cómo escribir los datos mediante mutaciones:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.commit do |c|
  c.insert "Singers", [
    { SingerId: 1, FirstName: "Marc",     LastName: "Richards" },
    { SingerId: 2, FirstName: "Catalina", LastName: "Smith"    },
    { SingerId: 3, FirstName: "Alice",    LastName: "Trentor"  },
    { SingerId: 4, FirstName: "Lea",      LastName: "Martin"   },
    { SingerId: 5, FirstName: "David",    LastName: "Lomond"   }
  ]
  c.insert "Albums", [
    { 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" }
  ]
end

puts "Inserted data"

Ejecuta la muestra con el argumento insert_data.

bundle exec ruby spanner_samples.rb insert_data test-instance example-db

Deberías ver lo siguiente:

Inserted data

Nota: Existen límites para el tamaño de confirmación. Consulta el límite de CRUD para obtener más información.

Consulta datos mediante SQL

Spanner admite una interfaz de SQL para leer datos, que puedes en la línea de comandos con Google Cloud CLI programáticamente con la biblioteca cliente de Spanner para Ruby.

En la línea de comandos

Ejecuta la siguiente instrucción de 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'

Nota: Para obtener la referencia de GoogleSQL, visita Sintaxis de consultas en GoogleSQL y, como referencia de PostgreSQL, consulta Estructura léxica y sintaxis de PostgreSQL.

El resultado debería ser este:

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

Usa la biblioteca cliente de Spanner para Ruby

Además de ejecutar una instrucción de SQL en la línea de comandos, puedes emitir la misma instrucción de SQL de manera programática con la biblioteca cliente de Spanner para Ruby.

Usa el método Client#execute para ejecutar la consulta de SQL. Usa un símbolo de Ruby :ColumnName para acceder a los datos de una columna específica en una fila.

Aquí se muestra cómo enviar la consulta y acceder a los datos:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.execute("SELECT SingerId, AlbumId, AlbumTitle FROM Albums").rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:AlbumTitle]}"
end

Ejecuta la muestra con el argumento query_data.

bundle exec ruby spanner_samples.rb query_data test-instance example-db

Deberías ver el siguiente resultado:

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

Consulta mediante un parámetro de SQL

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

Este es un ejemplo del uso de un parámetro en la cláusula WHERE para Consultar registros que contengan un valor específico para LastName.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

sql_query = "SELECT SingerId, FirstName, LastName
             FROM Singers
             WHERE LastName = @lastName"

params      = { lastName: "Garcia" }
param_types = { lastName: :STRING }

client.execute(sql_query, params: params, types: param_types).rows.each do |row|
  puts "#{row[:SingerId]} #{row[:FirstName]} #{row[:LastName]}"
end

Ejecuta la muestra con el argumento query_with_parameter.

bundle exec ruby spanner_samples.rb query_with_parameter test-instance example-db

Deberías ver el siguiente resultado:

12 Melissa Garcia

Lee datos con la API de lectura

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

Usa el método Client#read de la clase Client para leer las filas de la base de datos.

Aquí te indicamos cómo leer los datos:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.read("Albums", [:SingerId, :AlbumId, :AlbumTitle]).rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:AlbumTitle]}"
end

Ejecuta la muestra con el argumento read_data.

bundle exec ruby spanner_samples.rb read_data test-instance example-db

Deberías ver un resultado similar a este:

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

Actualiza el esquema de la base de datos

Supongamos que necesitas agregar una columna nueva llamada MarketingBudget a la tabla Albums. Para agregar una columna nueva a una tabla existente, es necesario actualizar el esquema de la base de datos. Spanner admite actualizaciones de esquema en una base de datos, mientras que base de datos siga entregando tráfico. Las actualizaciones de esquema no requieren la base de datos sin conexión y no bloquean tablas ni columnas enteras; puedes continuar la escritura de datos en la base de datos durante la actualización del esquema. Más información sobre las las actualizaciones y el rendimiento de los cambios de esquema Realiza actualizaciones del esquema.

Agrega una columna

Puedes agregar una columna en la línea de comandos con Google Cloud CLI o programáticamente con la biblioteca cliente de Spanner para Ruby.

En la línea de comandos

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

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'

Deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Spanner para Ruby

Usa el método Database#update de la clase Database para modificar el esquema:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

db_path = database_admin_client.database_path project: project_id,
                                              instance: instance_id,
                                              database: database_id

job = database_admin_client.update_database_ddl database: db_path,
                                                statements: [
                                                  "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"
                                                ]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the MarketingBudget column"

Ejecuta la muestra con el argumento add_column.

bundle exec ruby spanner_samples.rb add_column test-instance example-db

Deberías ver lo siguiente:

Added the MarketingBudget column

Escribe datos en la columna nueva

Con el siguiente código, se escriben datos en la columna nueva. Establece MarketingBudget en 100000 para la fila marcada por Albums(1, 1) y en 500000 para la fila marcada por Albums(2, 2).

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.commit do |c|
  c.update "Albums", [
    { SingerId: 1, AlbumId: 1, MarketingBudget: 100_000 },
    { SingerId: 2, AlbumId: 2, MarketingBudget: 500_000 }
  ]
end

puts "Updated data"

Ejecuta la muestra con el argumento update_data.

bundle exec ruby spanner_samples.rb update_data test-instance example-db

Deberías ver lo siguiente:

Updated data

También puedes ejecutar una consulta de SQL o una llamada de lectura para recuperar los valores que acabas de escribir.

Este es el código para ejecutar la consulta:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.execute("SELECT SingerId, AlbumId, MarketingBudget FROM Albums").rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:MarketingBudget]}"
end

Para ejecutar esta consulta, ejecuta la muestra con el argumento query_data_with_new_column.

bundle exec ruby spanner_samples.rb query_data_with_new_column test-instance example-db

Debería ver lo siguiente:

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

Actualiza datos

Puedes actualizar los datos mediante DML en una transacción de lectura y escritura.

Usa el método execute_update() para ejecutar una declaración DML.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner         = Google::Cloud::Spanner.new project: project_id
client          = spanner.client instance_id, database_id
transfer_amount = 200_000

client.transaction do |transaction|
  first_album = transaction.execute(
    "SELECT MarketingBudget from Albums
     WHERE SingerId = 1 and AlbumId = 1"
  ).rows.first
  second_album = transaction.execute(
    "SELECT MarketingBudget from Albums
    WHERE SingerId = 2 and AlbumId = 2"
  ).rows.first
  raise "The second album does not have enough funds to transfer" if second_album[:MarketingBudget] < transfer_amount

  new_first_album_budget  = first_album[:MarketingBudget] + transfer_amount
  new_second_album_budget = second_album[:MarketingBudget] - transfer_amount

  transaction.execute_update(
    "UPDATE Albums SET MarketingBudget = @albumBudget WHERE SingerId = 1 and AlbumId = 1",
    params: { albumBudget: new_first_album_budget }
  )
  transaction.execute_update(
    "UPDATE Albums SET MarketingBudget = @albumBudget WHERE SingerId = 2 and AlbumId = 2",
    params: { albumBudget: new_second_album_budget }
  )
end

puts "Transaction complete"

Ejecuta la muestra con el argumento write_with_transaction_using_dml.

bundle exec ruby spanner_samples.rb write_with_transaction_using_dml test-instance example-db

Deberías ver lo siguiente:

Transaction complete

Nota: También puedes actualizar datos mediante mutaciones.

Usa un índice secundario

Supongamos que deseas recuperar todas las filas de Albums que tienen valores AlbumTitle en un rango determinado. Puedes leer todos los valores de la columna AlbumTitle con una instrucción de SQL o una llamada de lectura y, luego, descartar las filas que no cumplan con los criterios. Sin embargo, analizar tablas enteras es costoso, especialmente si tienen muchas filas. En su lugar, crea un índice secundario en la tabla para acelerar la recuperación de filas cuando realizas búsquedas por columnas sin claves primarias.

Para agregar un índice secundario a una tabla existente, es necesario actualizar el esquema. Al igual que otras actualizaciones de esquema, Spanner admite que se agregue un índice mientras la base de datos continúa entregando tráfico. Spanner reabastece de manera automática el índice con tus datos existentes. Los reabastecimientos pueden tardar unos minutos en completarse, pero no es necesario que uses la base de datos sin conexión ni que evites escribir en la tabla indexada durante este proceso. Para obtener más detalles, consulta Cómo agregar un índice secundario.

Después de agregar un índice secundario, Spanner lo usa automáticamente para lo siguiente: Consultas de SQL que tienen probabilidades de ejecutarse más rápido con el índice. Si usas la interfaz de lectura, debes especificar el índice que deseas usar.

Agrega un índice secundario

Puedes agregar un índice en la línea de comandos con gcloud CLI o de forma programática con la biblioteca cliente de Spanner para Ruby.

En la línea de comandos

Usa 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 lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Spanner para Ruby

Usa el método Database#update de la clase Database para agregar un índice:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

db_path = database_admin_client.database_path project: project_id,
                                              instance: instance_id,
                                              database: database_id

job = database_admin_client.update_database_ddl database: db_path,
                                                statements: [
                                                  "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
                                                ]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the AlbumsByAlbumTitle index"

Ejecuta la muestra con el argumento create_index.

bundle exec ruby spanner_samples.rb create_index test-instance example-db

Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:

Added the AlbumsByAlbumTitle index

Leer con el índice

Para las consultas en SQL, Spanner usa automáticamente un índice adecuado. En la interfaz de lectura, debes especificar el índice en tu solicitud.

Para usar el índice en la interfaz de lectura, proporciona un parámetro index al método read de la clase Client.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

result = client.read "Albums", [:AlbumId, :AlbumTitle],
                     index: "AlbumsByAlbumTitle"

result.rows.each do |row|
  puts "#{row[:AlbumId]} #{row[:AlbumTitle]}"
end

Ejecuta la muestra con el argumento read_data_with_index.

bundle exec ruby spanner_samples.rb read_data_with_index test-instance example-db

Deberías ver lo siguiente:

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

Agrega un índice para lecturas de solo índice

Quizás hayas notado que el ejemplo de lectura anterior no incluye la lectura la columna MarketingBudget Esto se debe a que la interfaz de lectura de no admite la capacidad de unir un índice con una tabla de datos para buscar valores que no se almacenan en el índice.

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

En la línea de comandos

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)

Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Spanner para Ruby

Usa el método Database#update de la clase Database para agregar un índice con una cláusula STORING:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

db_path = database_admin_client.database_path project: project_id,
                                              instance: instance_id,
                                              database: database_id

job = database_admin_client.update_database_ddl database: db_path,
                                                statements: [
                                                  "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle)
   STORING (MarketingBudget)"
                                                ]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the AlbumsByAlbumTitle2 storing index"

Ejecuta la muestra con el argumento create_storing_index.

bundle exec ruby spanner_samples.rb create_storing_index test-instance example-db

Deberías ver lo siguiente:

Added the AlbumsByAlbumTitle2 index

Ahora puedes ejecutar una operación de lectura que recupere todas las columnas AlbumId, AlbumTitle y MarketingBudget del índice AlbumsByAlbumTitle2:

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

result = client.read "Albums", [:AlbumId, :AlbumTitle, :MarketingBudget],
                     index: "AlbumsByAlbumTitle2"

result.rows.each do |row|
  puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:MarketingBudget]}"
end

Ejecuta la muestra con el argumento read_data_with_storing_index.

bundle exec ruby spanner_samples.rb read_data_with_storing_index test-instance example-db

Deberías ver un resultado similar a este:

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

Recupera datos mediante transacciones de solo lectura

Supongamos que quieres ejecutar más de una lectura en la misma marca de tiempo. Las transacciones de solo lectura utilizan un prefijo coherente del historial de confirmaciones de transacciones, por lo que la aplicación siempre obtiene datos coherentes. Usa un objeto Snapshot para ejecutar transacciones de solo lectura. Usa el método snapshot de la clase Client para obtener un objeto Snapshot.

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

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.snapshot do |snapshot|
  snapshot.execute("SELECT SingerId, AlbumId, AlbumTitle FROM Albums").rows.each do |row|
    puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:SingerId]}"
  end

  # Even if changes occur in-between the reads, the transaction ensures that
  # both return the same data.
  snapshot.read("Albums", [:AlbumId, :AlbumTitle, :SingerId]).rows.each do |row|
    puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:SingerId]}"
  end
end

Ejecuta la muestra con el argumento read_only_transaction.

bundle exec ruby spanner_samples.rb read_only_transaction test-instance example-db

Deberías ver un resultado similar a este:

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

Limpieza

Para evitar que se apliquen cargos adicionales a tu cuenta de Google Cloud por los recursos que se usaron en este instructivo, descarta la base de datos y borra la instancia que creaste.

Borra la base de datos

Si borras una instancia, se borrarán de forma automática todas las bases de datos que contiene. En este paso, se muestra cómo borrar una base de datos sin borrar una instancia (ten en cuenta que se seguirán generando cargos por la instancia).

En la línea de comandos

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

Usa la consola de Google Cloud

1. Ve a la página Instancias de Spanner en la consola de Google Cloud.

   Ir a la página Instancias

2. Haz clic en la instancia.

3. Haz clic en la base de datos que deseas borrar.

4. En la página Detalles de la base de datos, haz clic en Borrar.

5. Confirma que deseas borrar la base de datos y haz clic en Borrar.

Borra la instancia

Si borras una instancia, se descartarán de forma automática todas las bases de datos creadas en ella.

En la línea de comandos

gcloud spanner instances delete test-instance

Usa la consola de Google Cloud

1. Ve a la página Instancias de Spanner en la consola de Google Cloud.

   Ir a la página Instancias

2. Haz clic en tu instancia.

3. Haz clic en Borrar.

4. Confirma que deseas borrar la instancia y haz clic en Borrar.

¿Qué sigue?

• Obtén información para acceder a Spanner con una instancia de máquina virtual.

• Obtén más información sobre las credenciales de autorización y autenticación en Autenticar en de Google Cloud con bibliotecas cliente.

• Obtén más información sobre las prácticas recomendadas para el diseño de esquemas de Spanner.