開始使用 Ruby 版 Spanner

目標

本教學課程將逐步引導您使用 Ruby 適用的 Spanner 用戶端程式庫進行下列步驟：

  • 建立 Spanner 執行個體和資料庫。
  • 對資料庫中的資料進行寫入和讀取，以及執行 SQL 查詢。
  • 更新資料庫結構定義。
  • 使用讀取/寫入交易來更新資料。
  • 將次要索引新增至資料庫。
  • 使用索引對資料執行讀取作業和 SQL 查詢。
  • 使用唯讀交易擷取資料。

費用

本教學課程使用 Spanner，這是Google Cloud的計費元件。如要瞭解 Spanner 的使用費用，請參閱「定價」一文。

事前準備

完成「設定」一文中說明的步驟，包含建立與設定預設的 Google Cloud 專案、啟用計費功能、啟用 Cloud Spanner API 和設定 OAuth 2.0 以取得使用 Cloud Spanner API 的驗證憑證。

特別提醒您，請務必執行 gcloud auth application-default login 來設定本機開發環境的驗證憑證。

準備本機 Ruby 環境

  1. 請在您的開發機器上安裝下列項目：

  2. 將範例應用程式存放區複製到您的本機電腦：

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

    您也可以下載 zip 格式的範例，然後解壓縮該檔案。

  3. 變更為包含 Spanner 範例程式碼的目錄：

    cd ruby-docs-samples/spanner/

  4. 安裝依附元件：

    bundle install

  5. 將 GOOGLE_CLOUD_PROJECT 環境變數設為您的 Google Cloud專案 ID：

    export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]

建立執行個體

首次使用 Spanner 時，您必須建立執行個體，這是 Spanner 資料庫會使用的資源分配單位。建立執行個體時，請選擇「執行個體設定」以決定資料儲存的位置，再選擇要使用的節點數量以決定執行個體的服務和儲存空間資源量。

執行下列指令，在 us-central1 地區使用 1 個節點建立 Spanner 執行個體：

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

請注意，如此將建立具備下列特性的執行個體：

  • 執行個體 ID test-instance
  • 顯示名稱 Test Instance
  • 執行個體設定 regional-us-central1 (地區設定會將資料儲存在一個地區，而多地區設定則會讓資料散佈在多個地區。詳情請參閱「關於執行個體」一文。
  • 節點數量 1 (node_count 與執行個體中的資料庫可用的服務和儲存空間資源數量相對應。詳情請參閱「節點和處理單元」一節)。

畫面上會顯示下列訊息：

Creating instance...done.

瀏覽範例檔案

範例存放區中有一項範例，說明如何透過 Ruby 使用 Spanner。

請查看 spanner_samples.rb 檔案，瞭解如何使用 Spanner。該檔案中的程式碼會顯示如何建立及使用新資料庫。這份資料會使用結構定義與資料模型頁面中顯示的範例結構定義。

建立資料庫

GoogleSQL 

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

PostgreSQL

bundle exec ruby spanner_postgresql_create_database.rb postgresql_create_database MY_PROJECT_ID test-instance example-db

畫面上會顯示下列訊息：

Created database example-db on instance test-instance
以下程式碼會建立資料庫，並在資料庫中建立兩個資料表。

GoogleSQL 

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

PostgreSQL

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

def postgresql_create_database project_id:, instance_id:, database_id:
  # project_id  = "Your Google Cloud project ID"
  # instance_id = "Your Spanner instance ID"
  # database_id = "Your Spanner database ID"

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

  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}\"",
                                              database_dialect: :POSTGRESQL

  puts "Waiting for create database operation to complete"

  job.wait_until_done!

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

下一個步驟是將資料寫入資料庫。

建立資料庫用戶端

您必須先建立 Client，才能執行讀取或寫入作業。您可以將 Client 視為一種資料庫連線：您與 Spanner 的所有互動都必須透過 Client。一般而言，您會在應用程式啟動時建立 Client，然後重複使用該 Client 進行讀取、寫入及執行交易。以下程式碼顯示如何建立用戶端。

# 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

詳情請參閱 Client 參考資料。

使用 DML 寫入資料

您可以使用資料操縱語言 (DML) 在讀寫交易中插入資料。

請使用 execute_update() 方法執行 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."

使用 write_using_dml 引數執行範例。

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

畫面上會顯示下列訊息：

 4 records inserted.

使用變異寫入資料

您也可以使用變異來插入資料。

您可以利用 Client 物件寫入資料。Client#commit 方法會建立並修訂寫入作業的交易，在資料庫的資料欄、資料列與資料表中，以不可分割的形式在單一邏輯點及時執行這些寫入作業。

此程式碼顯示如何使用變異寫入資料：

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

使用 insert_data 引數執行範例。

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

畫面上會顯示下列訊息：

Inserted data

使用 SQL 查詢資料

Spanner 支援可用於讀取資料的 SQL 介面。您可以透過 Google Cloud CLI 在指令列上存取這個介面，或者透過程式輔助方式使用 Ruby 專屬的 Spanner 用戶端程式庫。

使用指令列

執行下列 SQL 陳述式，從 Albums 資料表讀取所有資料欄的值：

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

結果應為：

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

使用 Ruby 適用的 Spanner 用戶端程式庫

除了在指令列上執行 SQL 陳述式之外，您也可以使用 Ruby 適用的 Spanner 用戶端程式庫，透過程式發出相同的 SQL 陳述式。

請利用 Client#execute 方法執行 SQL 查詢。使用 Ruby 符號 :ColumnName，從某一資料列存取特定資料欄的資料。

下面說明如何發出查詢和存取資料：

# 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

使用 query_data 引數執行範例。

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

畫面上應會顯示下列結果：

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

使用 SQL 參數執行查詢

如果應用程式有經常執行的查詢，您可以透過參數化來提升效能。系統可快取並重新使用產生的參數查詢，減少編譯的成本。詳情請參閱「使用查詢參數，針對經常執行的查詢加快速度」。

以下範例說明如何在 WHERE 子句中使用參數，查詢包含 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

使用 query_with_parameter 引數執行範例。

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

畫面上應會顯示下列結果：

12 Melissa Garcia

使用讀取 API 讀取資料

除了 Spanner 的 SQL 介面外，Spanner 也支援讀取介面。

使用 Client 類別的 Client#read 方法，從資料庫讀取資料列。

下列內容將示範如何讀取資料：

# 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

使用 read_data 引數執行範例。

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

畫面會顯示類似以下的輸出：

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

更新資料庫結構定義

假設您需要新增名稱為 MarketingBudget 的新資料欄到 Albums 資料表，必須先更新資料庫結構定義，才能新增新資料欄到現有的資料表。Spanner 可在資料庫持續處理流量時，支援資料庫的結構定義更新作業。結構定義更新作業不需要讓資料庫離線，也不會鎖定整個資料表或資料欄；您可以在結構定義更新期間持續將資料寫入資料庫。詳情請參閱進行結構定義更新一文中支援的結構定義更新和結構定義變更效能。

新增資料欄

您可以使用 Google Cloud CLI 在指令列上新增資料欄，或者透過程式使用 Ruby 專用的 Spanner 用戶端程式庫。

使用指令列

使用下列 ALTER TABLE 指令，在資料表中新增資料欄：

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'

畫面上會顯示下列訊息：

Schema updating...done.

使用 Ruby 專用的 Spanner 用戶端程式庫

請使用 Database 類別的 Database#update 方法修改結構定義：

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

使用 add_column 引數執行範例。

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

畫面上會顯示下列訊息：

Added the MarketingBudget column

寫入資料到新資料欄

以下程式碼會將資料寫入新資料欄，並在 Albums(1, 1) 和 Albums(2, 2) 這兩個索引鍵表示的資料列中將 MarketingBudget 分別設為 100000 和 500000。

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

使用 update_data 引數執行範例。

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

畫面上會顯示下列訊息：

Updated data

您也可以執行 SQL 查詢或讀取呼叫，以擷取剛寫入的值。

以下是執行查詢的程式碼：

# 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

如要執行這項查詢，請使用 query_data_with_new_column 引數執行範例檔案。

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

畫面上會顯示下列訊息：

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

更新資料

您可以在讀寫交易中使用 DML 來更新資料。

請使用 execute_update() 方法執行 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"

使用 write_with_transaction_using_dml 引數執行範例。

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

畫面上會顯示下列訊息：

Transaction complete

使用次要索引

假設您要針對 Albums 擷取 AlbumTitle 值在特定範圍內的所有資料列，可以先利用 SQL 陳述式或讀取呼叫，從 AlbumTitle 資料欄讀取所有值，然後再捨棄條件不符的資料列。不過，執行完整資料表掃描的費用高昂，對於內含大量資料列的資料表而言更是如此。因此您可以改為在資料表建立次要索引，以在將非主鍵資料欄做為搜尋條件時，能加快資料列的擷取速度。

您必須先更新結構定義，才能將次要索引新增至現有資料表。如同其他結構定義更新，Spanner 支援在資料庫持續處理流量時新增索引。Spanner 會自動使用現有資料填入索引。補充作業可能需要幾分鐘才能完成，但您不必將資料庫設為離線，也不必避免在這個程序中寫入已編入索引的資料表。詳情請參閱「新增次要索引」。

新增次要索引後，Spanner 會自動將其用於 SQL 查詢，這些查詢可能會在使用索引後執行得更快。如果您使用讀取介面，則必須指定要使用的索引。

新增次要索引

您可以使用 gcloud CLI 在指令列上新增索引，或透過程式使用 Ruby 適用的 Spanner 用戶端程式庫。

使用指令列

使用下列 CREATE INDEX 指令，在資料庫中新增索引：

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

畫面上會顯示下列訊息：

Schema updating...done.

使用 Ruby 專用的 Spanner 用戶端程式庫

使用 Database 類別的 Database#update 方法新增索引：

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

使用 create_index 引數執行範例。

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

索引可能需要幾分鐘才能新增完成。之後畫面上會顯示以下訊息：

Added the AlbumsByAlbumTitle index

使用索引進行讀取

對於 SQL 查詢，Spanner 會自動使用適當的索引。在讀取介面中，您必須在要求中指定索引。

如要在讀取介面中使用索引，請為 Client 類別的 read 方法提供 index 參數。

# 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

使用 read_data_with_index 引數執行範例。

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

畫面上會顯示下列訊息：

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

新增索引以便僅讀取索引

您可能已經注意到，先前的讀取範例並未包含讀取 MarketingBudget 資料欄。這是因為 Spanner 的讀取介面不支援將索引與資料表彙整，再查詢未保存於索引中的值。

請為 AlbumsByAlbumTitle 建立替代定義，將 MarketingBudget 的副本保存在索引中。

使用指令列

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)

索引可能需要幾分鐘才能新增完成。之後畫面上會顯示以下訊息：

Schema updating...done.

使用 Ruby 專用的 Spanner 用戶端程式庫

使用 Database 類別的 Database#update 方法，透過 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"

使用 create_storing_index 引數執行範例。

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

畫面上會顯示下列訊息：

Added the AlbumsByAlbumTitle2 index

現在您可以執行讀取作業，從 AlbumsByAlbumTitle2 索引中擷取所有 AlbumId、AlbumTitle 和 MarketingBudget 欄：

# 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

使用 read_data_with_storing_index 引數執行範例。

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

畫面會顯示類似以下的輸出：

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

使用唯讀交易擷取資料

假設您想要在相同時間戳記執行一次以上的讀取作業。唯讀交易會觀察出交易修訂記錄中一致的前置字串，讓應用程式取得的資料始終保持一致。如要執行唯讀交易，請使用 Snapshot 物件。請使用 Client 類別的 snapshot 方法取得 Snapshot 物件。

以下顯示如何執行查詢，並在同一個唯讀交易中執行讀取作業：

# 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

使用 read_only_transaction 引數執行範例。

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

畫面會顯示類似以下的輸出：

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

清除所用資源

如要避免系統向您的 Cloud Billing 帳戶收取您在本教學課程中所用資源的額外費用，請捨棄資料庫並刪除您建立的執行個體。

刪除資料庫

您刪除執行個體時，也會自動刪除其中所有資料庫。這個步驟將示範如何在保留執行個體的情況下刪除資料庫 (您仍須支付執行個體費用)。

使用指令列

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

使用 Google Cloud 主控台

  1. 前往 Google Cloud 控制台的「Spanner 執行個體」頁面。

    前往「Instances」(執行個體) 頁面

  2. 點選執行個體。

  3. 點選您要刪除的資料庫。

  4. 在「Database details」(資料庫詳細資料) 頁面，按一下 [Delete] (刪除)。

  5. 確認您要刪除資料庫，然後按一下 [Delete] (刪除)。

刪除執行個體

您刪除執行個體時，也會自動捨棄您在其中建立的所有資料庫。

使用指令列

gcloud spanner instances delete test-instance

使用 Google Cloud 主控台

  1. 前往 Google Cloud 控制台的「Spanner 執行個體」頁面。

    前往「Instances」(執行個體) 頁面

  2. 點選執行個體。

  3. 按一下 [Delete] (刪除)。

  4. 確認您要刪除執行個體，然後按一下 [Delete] (刪除)。

後續步驟