Erste Schritte mit Cloud Spanner in Ruby

Lernziele

In dieser Anleitung werden Sie durch die folgenden Schritte mit der Cloud Spanner-Clientbibliothek für Ruby geführt:

  • Cloud Spanner-Instanz und -Datenbank erstellen
  • SQL-Abfragen für Daten in der Datenbank schreiben, lesen und ausführen
  • Datenbankschema aktualisieren
  • Daten mit einer Lese-Schreib-Transaktion aktualisieren
  • Sekundären Index für die Datenbank hinzufügen
  • Mit dem Index Daten lesen und SQL-Abfragen ausführen
  • Daten über eine schreibgeschützte Transaktion abrufen

Kosten

In dieser Anleitung wird Cloud Spanner verwendet, eine kostenpflichtige Komponente von Google Cloud. Informationen zu den Kosten der Nutzung von Cloud Spanner finden Sie unter Preise.

Vorbereitung

Führen Sie die unter Einrichten beschriebenen Schritte aus, die das Erstellen und Festlegen eines standardmäßigen Google Cloud-Projekts, das Aktivieren der Rechnungsstellung, das Aktivieren der Cloud Spanner API und das Einrichten von OAuth 2.0 umfassen, um Anmeldedaten für die Authentifizierung für die Verwendung der Cloud Spanner API zu erhalten.

Sie müssen insbesondere gcloud auth application-default login ausführen, um die lokale Entwicklungsumgebung mit Anmeldedaten für die Authentifizierung einzurichten.

Lokale Ruby-Umgebung vorbereiten

  1. Installieren Sie Folgendes auf dem Entwicklungscomputer, sofern nicht bereits vorhanden:

  2. Klonen Sie das Repository der Beispielanwendung auf Ihren lokalen Computer:

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

    Sie können das Beispiel auch als ZIP-Datei herunterladen und extrahieren.

  3. Wechseln Sie in das Verzeichnis, das den Cloud Spanner-Beispielcode enthält:

    cd ruby-docs-samples/spanner/
    
  4. Installieren Sie die Abhängigkeiten:

    bundle install
    
  5. Legen Sie als GOOGLE_PROJECT_ID-Umgebungsvariable Ihre Projekt-ID für die Google Cloud Platform fest.

    export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]
    

Instanz erstellen

Wenn Sie Cloud Spanner zum ersten Mal verwenden, müssen Sie eine Instanz erstellen. Dabei handelt es sich um eine Zuordnung von Ressourcen, die von Cloud Spanner-Datenbanken verwendet werden. Wenn Sie eine Instanz erstellen, müssen Sie eine Instanzkonfiguration auswählen. Abhängig davon werden der Speicherort Ihrer Daten sowie die Anzahl der zu verwendenden Knoten festgelegt. Anhand der Knotenanzahl wird dann die Menge der Bereitstellungs- und Speicherressourcen in Ihrer Instanz festgelegt.

Führen Sie den folgenden Befehl aus, um eine Cloud Spanner-Instanz in der Region us-central1 mit nur einem Knoten zu erstellen:

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

Dadurch wird eine Instanz mit diesen Properties erstellt:

  • Instanz-ID test-instance
  • Anzeigename Test Instance
  • Instanzkonfiguration regional-us-central1 – Bei regionalen Konfigurationen werden Daten in nur einer Region gespeichert, während sie bei multiregionalen Konfigurationen auf mehrere Regionen verteilt werden. Weitere Informationen dazu finden Sie unter Instanzen.
  • Knotenanzahl 1 – node_count entspricht der Anzahl der Bereitstellungs- und Speicherressourcen in der Instanz, die für Datenbanken zur Verfügung stehen. Weitere Informationen dazu finden Sie unter Knotenzahl.

Hier sollten Sie das sehen:

Creating instance...done.

Beispieldateien ansehen

Das Beispiel-Repository enthält ein Beispiel für die Verwendung von Cloud Spanner mit Ruby.

Sehen Sie sich die Datei spanner_samples.rb genauer an. Darin wird die Verwendung von Cloud Spanner dargestellt. Der Code zeigt, wie eine neue Datenbank erstellt und verwendet wird. In den Daten wird das Beispielschema verwendet, das auf der Seite Schema und Datenmodell dargestellt ist.

Datenbank erstellen

Erstellen Sie eine Datenbank mit dem Namen example-db in der Instanz test-instance, indem Sie Folgendes in der Befehlszeile ausführen:

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

Hier sollten Sie das sehen:

Created database example-db on instance test-instance

Sie haben gerade eine Cloud Spanner-Datenbank erstellt. Die Datenbank wurde aus diesem Code erstellt:

# 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
instance = spanner.instance instance_id

job = instance.create_database database_id, 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}"

Mit dem Code werden außerdem die beiden Tabellen Singers und Albums für eine einfache Musikanwendung definiert. Die Tabellen werden im weiteren Verlauf dieser Seite verwendet. Sehen Sie sich das Beispielschema an, falls Sie es noch nicht getan haben.

Im nächsten Schritt werden Daten in die Datenbank geschrieben.

Datenbankclient erstellen

Zum Ausführen von Lese- oder Schreibvorgängen müssen Sie einen Client erstellen. Sie können sich einen Client wie eine Datenbankverbindung vorstellen: Alle Interaktionen mit Cloud Spanner müssen einen Client durchlaufen. In der Regel erstellen Sie beim Starten Ihrer Anwendung einen Client. Anschließend verwenden Sie den Client zum Lesen, Schreiben und Ausführen von Transaktionen. Der folgende Code zeigt, wie Sie einen Client erstellen.

# 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
database_client.transaction do |transaction|
  results = transaction.execute "SELECT 1"

  results.rows.each do |row|
    puts row
  end
end

Weitere Informationen finden Sie in der Referenz zu Client.

Daten mit DML schreiben

Sie können Daten mit der Datenbearbeitungssprache (Data Manipulation Language, DML) in eine Lese-Schreib-Transaktion einfügen.

Für das Ausführen einer DML-Anweisung verwenden Sie die Methode execute_update().

# 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."

Führen Sie das Beispiel mit dem Argument write_using_dml aus.

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

Hier sollten Sie das sehen:

 4 records inserted.

Daten mit Mutationen schreiben

Sie können Daten auch mithilfe von Mutationen einfügen.

Daten werden mit einem Client-Objekt geschrieben. Mit der Methode Client#commit werden Transaktionen für Schreibvorgänge erstellt, die für Spalten, Zeilen und Tabellen in einer Datenbank zu einem einzigen logischen Zeitpunkt als unteilbarer Vorgang ausgeführt werden. Danach werden sie mit Commits festgeschrieben.

Dieser Code zeigt, wie die Daten mithilfe von Mutationen geschrieben werden:

# 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"

Führen Sie das Beispiel mit dem Argument insert_data aus.

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

Hier sollten Sie das sehen:

Inserted data

Daten mit SQL abfragen

Cloud Spanner unterstützt eine native SQL-Oberfläche zum Lesen von Daten, auf die Sie in der Befehlszeile mit dem gcloud-Befehlszeilentool oder programmatisch mit der Cloud Spanner-Clientbibliothek für Ruby zugreifen können.

Über die Befehlszeile

Führen Sie die folgende SQL-Anweisung aus, damit Sie die Werte aller Spalten aus der Tabelle Albums lesen können:

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

Das Ergebnis sollte so aussehen:

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

Mit der Cloud Spanner-Clientbibliothek für Ruby

Als Alternative zum Ausführen einer SQL-Anweisung in der Befehlszeile können Sie die gleiche SQL-Anweisung programmgesteuert mithilfe der Cloud Spanner-Clientbibliothek für Ruby ausführen.

Verwenden Sie die Methode Client#execute zum Ausführen der SQL-Abfrage. Über das Ruby-Symbol :ColumnName können Sie auf Daten für eine bestimmte Spalte aus einer Zeile zugreifen.

So geben Sie die Abfrage aus und greifen auf die Daten zu:

# 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

Führen Sie das Beispiel mit dem Argument query_data aus.

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

Sie sollten folgendes Ergebnis sehen:

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

Abfrage mit einem SQL-Parameter

Sie können mithilfe von Parametern benutzerdefinierte Werte in SQL-Anweisungen einfügen. Im Folgenden sehen Sie ein Beispiel für die Verwendung von @lastName als Parameter in der WHERE-Klausel zum Abfragen von Datensätzen, die einen bestimmten Wert für LastName enthalten.

# 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

Führen Sie das Beispiel mit dem Argument "query_with_parameter" aus.

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

Sie sollten folgendes Ergebnis sehen:

12 Melissa Garcia

Daten mit der Lese-API auslesen

Neben der SQL-Schnittstelle unterstützt Cloud Spanner auch eine Leseschnittstelle.

Verwenden Sie die Methode Client#read der Klasse Client, um Zeilen aus der Datenbank zu lesen.

So lesen Sie die Daten aus:

# 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

Führen Sie das Beispiel mit dem Argument read_data aus.

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

Die Ausgabe sollte etwa so aussehen:

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

Datenbankschema aktualisieren

Beispiel: Sie müssen eine neue Spalte namens MarketingBudget zur Tabelle Albums hinzufügen. Damit einer vorhandenen Tabelle eine neue Spalte hinzugefügt werden kann, muss das Datenbankschema aktualisiert werden. Cloud Spanner unterstützt Schemaaktualisierungen für Datenbanken, ohne dass die Traffic-Bereitstellung unterbrochen werden muss. Bei einer Schemaaktualisierung muss die Datenbank nicht offline geschaltet und es müssen keine ganzen Tabellen oder Spalten gesperrt werden. Sie können während der Aktualisierung weiter Daten in die Datenbank schreiben. Weitere Informationen zu unterstützten Schemaaktualisierungen und zur Leistung während der Schemaänderung finden Sie unter Schemaaktualisierungen.

Spalte hinzufügen

Sie können eine Spalte in der Befehlszeile mithilfe des gcloud-Befehlszeilentools oder programmatisch mithilfe der Cloud Spanner-Clientbibliothek für Ruby hinzufügen.

Über die Befehlszeile

Verwenden Sie den folgenden Befehl ALTER TABLE, um die neue Spalte zur Tabelle hinzuzufügen:

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

Hier sollten Sie dies sehen:

Schema updating...done.

Mit der Cloud Spanner-Clientbibliothek für Ruby

Verwenden Sie die Methode Database#update der Klasse Database, um das Schema zu ändern:

# 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
instance = spanner.instance instance_id
database = instance.database database_id

job = database.update statements: [
  "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"
]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the MarketingBudget column"

Führen Sie das Beispiel mit dem Argument add_column aus.

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

Hier sollten Sie das sehen:

Added the MarketingBudget column

Daten in die neue Spalte schreiben

Mit dem folgenden Code werden Daten in die neue Spalte geschrieben. Er legt für MarketingBudget den Wert 100000 für den Zeilenschlüssel fest, der durch Albums(1, 1) angegeben wird, und er legt 500000 für den Zeilenschlüssel fest, der durch Albums(2, 2) angegeben wird.

# 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"

Führen Sie das Beispiel mit dem Argument update_data aus.

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

Hier sollten Sie dies sehen:

Updated data

Sie können auch eine SQL-Abfrage oder einen Leseaufruf ausführen, um die Werte abzurufen, die Sie gerade geschrieben haben.

Mit diesem Code können Sie die Abfrage ausführen:

# 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

Für diese Abfrage führen Sie das Beispiel mit dem Argument query_data_with_new_column aus.

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

Hier sollten Sie das sehen:

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

Daten aktualisieren

Sie können Daten mit DML in einer Lese-Schreib-Transaktion aktualisieren.

Für das Ausführen einer DML-Anweisung verwenden Sie die Methode execute_update().

# 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"

Führen Sie das Beispiel mit dem Argument write_with_transaction_using_dml aus.

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

Hier sollten Sie das sehen:

Transaction complete

Sekundären Index verwenden

Beispiel: Sie möchten alle Zeilen aus Albums abrufen, deren Wert für AlbumTitle in einem bestimmten Bereich liegen. Sie könnten dazu alle Werte aus der Spalte AlbumTitle mit einer SQL-Anweisung oder einem Leseaufruf lesen und dann die Zeilen verwerfen, die die Kriterien nicht erfüllen. Dieser vollständige Tabellenscan wäre jedoch sehr kostspielig, insbesondere bei Tabellen mit vielen Zeilen. Stattdessen können Sie einen sekundären Index für die Tabelle erstellen und damit das Abrufen von Zeilen beim Suchen über Spalten mit nicht primärem Schlüssel beschleunigen.

Damit ein sekundärer Index einer vorhandenen Tabelle hinzugefügt werden kann, muss das Schema aktualisiert werden. Wie bei anderen Schemaaktualisierungen kann mit Cloud Spanner ein Index hinzugefügt werden, ohne dass die Traffic-Bereitstellung unterbrochen werden muss. Cloud Spanner verwendet dann automatisch die vorhandenen Daten, um einen Backfill für den Index auszuführen. Backfills können einige Minuten dauern. Sie müssen aber die Datenbank nicht offline schalten und können während des Vorgangs weiter in die indexierten Tabellen schreiben. Weitere Informationen finden Sie unter Index-Backfill.

Nachdem Sie einen sekundären Index hinzugefügt haben, verwendet Cloud Spanner diesen automatisch für SQL-Abfragen, die mit dem Index sehr wahrscheinlich schneller ausgeführt werden. Wenn Sie die Leseschnittstelle verwenden, müssen Sie den Index angeben, den Sie nutzen möchten.

Sekundären Index hinzufügen

Sie können einen Index in der Befehlszeile mithilfe des gcloud-Befehlszeilentools oder programmatisch mithilfe der Cloud Spanner-Clientbibliothek für Ruby hinzufügen.

Über die Befehlszeile

Verwenden Sie den folgenden Befehl CREATE INDEX, um der Datenbank einen Index hinzuzufügen:

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

Hier sollten Sie dies sehen:

Schema updating...done.

Mit der Cloud Spanner-Clientbibliothek für Ruby

Verwenden Sie die Methode Database#update der Klasse Database, um einen Index hinzuzufügen:

# 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
instance = spanner.instance instance_id
database = instance.database database_id

job = database.update statements: [
  "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)"
]

puts "Waiting for database update to complete"

job.wait_until_done!

puts "Added the AlbumsByAlbumTitle index"

Führen Sie das Beispiel mit dem Argument create_index aus.

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

Das Hinzufügen eines Index kann einige Minuten dauern. Nachdem der Index hinzugefügt wurde, sollten Sie das sehen:

Added the AlbumsByAlbumTitle index

Mit dem Index auslesen

Für SQL-Abfragen verwendet Cloud Spanner automatisch einen geeigneten Index. In der Leseschnittstelle müssen Sie den Index in Ihrer Anfrage angeben.

Um den Index in der Leseschnittstelle zu verwenden, stellen Sie der Methode read der Klasse Client einen index-Parameter bereit.

# 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

Führen Sie das Beispiel mit dem Argument read_data_with_index aus.

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

Hier sollten Sie das sehen:

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

Index mit einer STORING-Klausel hinzufügen

Vielleicht haben Sie bemerkt, dass im obigen Beispiel die Spalte MarketingBudget nicht gelesen wird. Die Leseschnittstelle von Cloud Spanner unterstützt nicht die Möglichkeit, einen Index mit einer Datentabelle zu verbinden, um Werte zu suchen, die nicht im Index gespeichert sind.

Erstellen Sie eine alternative Definition von AlbumsByAlbumTitle, die eine Kopie von MarketingBudget im Index speichert.

Über die Befehlszeile

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

Das Hinzufügen eines Index kann einige Minuten dauern. Nachdem der Index hinzugefügt wurde, sollten Sie dies sehen:

Schema updating...done.

Mit der Cloud Spanner-Clientbibliothek für Ruby

Verwenden Sie die Methode Database#update der Klasse Database, um einen Index mit einer STORING-Klausel hinzuzufügen:

# 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
instance = spanner.instance instance_id
database = instance.database database_id

job = database.update 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"

Führen Sie das Beispiel mit dem Argument create_storing_index aus.

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

Hier sollten Sie dies sehen:

Added the AlbumsByAlbumTitle2 index

Jetzt können Sie einen Lesevorgang ausführen, der alle Spalten AlbumId, AlbumTitle und MarketingBudget aus dem Index AlbumsByAlbumTitle2 abruft:

# 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

Führen Sie das Beispiel mit dem Argument read_data_with_storing_index aus.

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

Die Ausgabe sollte etwa so aussehen:

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

Daten mit schreibgeschützten Transaktionen abrufen

Angenommen, Sie möchten mit einem Zeitstempel mehr als einen Lesevorgang ausführen. Bei schreibgeschützten Transaktionen wird ein gleichbleibendes Präfix des Commit-Verlaufs der Transaktionen beibehalten, damit die Anwendung immer konsistente Daten erhält. Verwenden Sie ein Snapshot-Objekt, um schreibgeschützte Transaktionen auszuführen. Verwenden Sie die Methode snapshot der Klasse Client, um ein Snapshot-Objekt zu erhalten.

So werden eine Abfrage und ein Lesevorgang in derselben schreibgeschützten Transaktion ausgeführt:

# 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

Führen Sie das Beispiel mit dem Argument read_only_transaction aus.

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

Die Ausgabe sollte etwa so aussehen:

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

Bereinigen

Löschen Sie die Datenbank und die erstellte Instanz, um zu vermeiden, dass Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen in Rechnung gestellt werden.

Datenbank löschen

Wenn Sie eine Instanz löschen, werden alle darin enthaltenen Datenbanken automatisch gelöscht. In diesem Schritt wird gezeigt, wie eine Datenbank gelöscht wird, ohne eine Instanz zu löschen (dabei fallen weiterhin Gebühren für die Instanz an).

Über die Befehlszeile

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

Mit der Cloud Console

  1. Rufen Sie in der Google Cloud Console die Seite Cloud Spanner-Instanzen auf.

    Zur Seite "Instanzen"

  2. Klicken Sie auf die Instanz.

  3. Klicken Sie auf die Datenbank, die Sie löschen möchten.

  4. Klicken Sie auf der Seite Datenbankdetails auf Löschen.

  5. Bestätigen Sie, dass die Datenbank gelöscht werden soll, und klicken Sie auf Löschen.

Instanz löschen

Beim Löschen einer Instanz werden alle Datenbanken, die in der Instanz erstellt wurden, automatisch gelöscht.

Über die Befehlszeile

gcloud spanner instances delete test-instance

Mit der Cloud Console

  1. Rufen Sie in der Google Cloud Console die Seite Cloud Spanner-Instanzen auf.

    Zur Seite "Instanzen"

  2. Klicken Sie auf die Instanz.

  3. Klicken Sie auf Löschen.

  4. Bestätigen Sie, dass die Instanz gelöscht werden soll, und klicken Sie auf Löschen.

Weitere Informationen

  • Über eine VM-Instanz auf Cloud Spanner zugreifen: Erstellen Sie eine VM-Instanz mit Zugriff auf die Cloud Spanner-Datenbank.
  • Anmeldedaten für die Autorisierung und Authentifizierung: Siehe Erste Schritte bei der Authentifizierung
  • Cloud Spanner-Konzepte