開始使用 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 資料庫所用的資源分配單位。建立執行個體時,請選擇「執行個體設定」以決定資料儲存的位置,再選擇要使用的節點數量以決定執行個體的服務和儲存空間資源量。

請參閱「建立執行個體」,瞭解如何使用下列任一方法建立 Spanner 執行個體。您可以將執行個體命名為 test-instance,以便與本文件中參照名為 test-instance 的執行個體的其他主題搭配使用。

  • Google Cloud CLI
  • Google Cloud 控制台
  • 用戶端程式庫 (C++、C#、Go、Java、Node.js、PHP、Python、Ruby 或 Rust)

瀏覽範例檔案

範例存放區包含一個範例,說明如何搭配使用 Spanner 和 Ruby。

查看 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 寫入資料

您可以在讀寫交易中使用 data manipulation language (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 資料表中所有資料欄的值:

GoogleSQL

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

GoogleSQL 管道語法

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

結果顯示:

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 值的記錄。

GoogleSQL

# 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

PostgreSQL

def spanner_postgresql_query_parameter 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"

  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 FirstName LIKE $1"
  params = { p1: "A%" }

  results = client.execute sql_query, params: params

  results.rows.each do |row|
    puts "SingerId: #{row[:singerid]}"
    puts "FirstName: #{row[:firstname]}"
    puts "LastName: #{row[:lastname]}"
  end
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

更新資料庫結構定義

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

新增資料欄

您可以使用 Google Cloud CLI 在指令列中新增資料欄,或使用 Spanner Ruby 用戶端程式庫,以程式輔助方式新增資料欄。

使用指令列

使用下列 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 方法修改結構定義:

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

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"

PostgreSQL

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

def spanner_postgresql_add_column 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"

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

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

  add_column_query = "ALTER TABLE Singers ADD COLUMN Age INTEGER"

  job = db_admin_client.update_database_ddl database: db_path,
                                            statements: [add_column_query]

  job.wait_until_done!

  if job.error?
    puts "Error while adding column. Code: #{job.error.code}. Message: #{job.error.message}"
    raise GRPC::BadStatus.new(job.error.code, job.error.message)
  end

  puts "Added Age column to Singers table in datbase #{database_id}"
end

使用 add_column 引數執行範例。

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

如下所示:

Added the MarketingBudget column

寫入資料到新資料欄

以下程式碼會將資料寫入新資料欄,這會將索引鍵為 Albums(1, 1) 的資料列 MarketingBudget 設為 100000,並將索引鍵為 Albums(2, 2) 的資料列設為 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 陳述式。

GoogleSQL

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

PostgreSQL

def spanner_postgresql_dml_getting_started_update 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"

  require "google/cloud/spanner"

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

  client.transaction do |transaction|
    transaction.execute_update(
      "UPDATE Singers SET Rating = $1 WHERE SingerId = 1",
      params: { p1: BigDecimal(4) },
      types: { p1: :PG_NUMERIC }
    )
  end

  puts "Transaction complete"
end

使用 write_with_transaction_using_dml 引數執行範例。

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

如下所示:

Transaction complete

使用次要索引

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

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

新增次要索引後,Spanner 會自動將其用於可能透過索引加快執行速度的 SQL 查詢。如果使用讀取介面,則必須指定要使用的索引。

新增次要索引

您可以使用 gcloud CLI 在指令列中新增索引,或使用 Spanner Ruby 用戶端程式庫,以程式輔助方式新增索引。

使用指令列

使用下列 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

使用索引進行讀取

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

如要在讀取介面中使用索引,請將 index 參數提供給 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

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 的讀取介面不支援透過 join 索引與資料表,再查詢未儲存於索引中的值。

建立 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」(Spanner 執行個體) 頁面。

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

  2. 點選執行個體。

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

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

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

刪除執行個體

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

使用指令列

gcloud spanner instances delete test-instance

使用 Google Cloud 控制台

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

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

  2. 點選執行個體。

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

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

後續步驟