Mulai menggunakan Spanner di Ruby

---

Catatan antarmuka PostgreSQL: Contoh dalam topik ini ditujukan untuk database dialek GoogleSQL.

Tujuan

Tutorial ini akan memandu Anda melalui langkah-langkah berikut menggunakan library klien Spanner untuk Ruby:

• Buat instance dan database Spanner.
• Menulis, membaca, dan menjalankan kueri SQL pada data di database.
• Perbarui skema database.
• Perbarui data menggunakan transaksi baca-tulis.
• Tambahkan indeks sekunder ke database.
• Gunakan indeks untuk membaca dan menjalankan kueri SQL pada data.
• Mengambil data menggunakan transaksi hanya baca.

Biaya

Tutorial ini menggunakan Spanner, yang merupakan komponenGoogle Cloudyang dapat ditagih. Untuk mengetahui informasi tentang biaya penggunaan Spanner, lihat Harga.

Sebelum memulai

Selesaikan langkah-langkah yang dijelaskan dalam Menyiapkan, yang mencakup pembuatan dan penetapan project Google Cloud default, pengaktifan penagihan, pengaktifan Cloud Spanner API, dan penyiapan OAuth 2.0 untuk mendapatkan kredensial autentikasi guna menggunakan Cloud Spanner API.

Khususnya, pastikan Anda menjalankan gcloud auth application-default login untuk menyiapkan lingkungan pengembangan lokal dengan kredensial autentikasi.

Catatan: Jika Anda tidak berencana untuk menyimpan resource yang Anda buat dalam tutorial ini, sebaiknya buat Google Cloud project baru, bukan memilih project yang sudah ada. Setelah menyelesaikan tutorial, Anda dapat menghapus project, sehingga semua resource yang terkait dengan project tersebut akan dihapus.

Menyiapkan lingkungan Ruby lokal Anda

1. Instal komponen berikut di mesin pengembangan Anda jika belum diinstal:

   • Ruby
   • Bundler

2. Clone repositori aplikasi contoh ke komputer lokal Anda:

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

   Atau, Anda dapat mendownload sampel sebagai file ZIP dan mengekstraknya.

3. Ubah ke direktori yang berisi kode contoh Spanner:

   cd ruby-docs-samples/spanner/
   

4. Instal dependensi:

   bundle install
   

5. Tetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT ke Google Cloud project ID Anda:

   export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]
   

Membuat instance

Saat pertama kali menggunakan Spanner, Anda harus membuat instance, yang merupakan alokasi resource yang digunakan oleh database Spanner. Saat membuat instance, Anda memilih konfigurasi instance, yang menentukan tempat penyimpanan data Anda, dan juga jumlah node yang akan digunakan, yang menentukan jumlah resource penayangan dan penyimpanan di instance Anda.

Jalankan perintah berikut untuk membuat instance Spanner di region us-central1 dengan 1 node:

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

Perhatikan bahwa perintah ini membuat instance dengan karakteristik berikut:

• ID Instance test-instance
• Nama tampilan Test Instance
• Konfigurasi instance regional-us-central1 (Konfigurasi regional menyimpan data di satu region, sementara konfigurasi multi-region mendistribusikan data di beberapa region. Untuk mengetahui informasi selengkapnya, lihat Tentang instance.)
• Jumlah node 1 (node_count sesuai dengan jumlah resource serving dan penyimpanan yang tersedia untuk database di instance. Pelajari lebih lanjut di Node dan unit pemrosesan.)

Anda akan melihat:

Creating instance...done.

Melihat-lihat file contoh

Repositori contoh berisi contoh yang menunjukkan cara menggunakan Spanner dengan Ruby.

Lihat file spanner_samples.rb, yang menunjukkan cara menggunakan Spanner. Kode ini menunjukkan cara membuat dan menggunakan database baru. Data menggunakan contoh skema yang ditampilkan di halaman Skema dan model data.

Buat database

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

Anda akan melihat:

Created database example-db on instance test-instance

Kode berikut membuat database dan dua tabel dalam database.

Catatan: Contoh kode berikutnya menggunakan kedua tabel ini. Jika Anda tidak menjalankan kode ini, buat tabel menggunakan konsol Google Cloud atau gcloud CLI. Untuk mengetahui informasi selengkapnya, lihat skema contoh.

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

Langkah berikutnya adalah menulis data ke database Anda.

Membuat klien database

Sebelum dapat melakukan operasi baca atau tulis, Anda harus membuat Client. Anda dapat menganggap Client sebagai koneksi database: semua interaksi Anda dengan Spanner harus melalui Client. Biasanya Anda membuat Client saat aplikasi Anda dimulai, lalu Anda menggunakan kembali Client tersebut untuk membaca, menulis, dan mengeksekusi transaksi. Kode berikut menunjukkan cara membuat klien.

# 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

Baca selengkapnya dalam referensi Client.

Menulis data dengan DML

Anda dapat menyisipkan data menggunakan Bahasa Pengolahan Data (DML) dalam transaksi baca-tulis.

Anda menggunakan metode execute_update() untuk menjalankan pernyataan 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."

Jalankan sampel menggunakan argumen write_using_dml.

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

Anda akan melihat:

 4 records inserted.

Catatan: Ada batasan untuk ukuran commit. Lihat batas CRUD untuk mengetahui informasi selengkapnya.

Menulis data dengan mutasi

Anda juga dapat menyisipkan data menggunakan mutasi.

Anda menulis data menggunakan objek Client. Metode Client#commit membuat dan melakukan transaksi untuk operasi tulis yang dieksekusi secara atomik pada satu titik waktu logis di seluruh kolom, baris, dan tabel dalam database.

Kode ini menunjukkan cara menulis data menggunakan mutasi:

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

Jalankan sampel menggunakan argumen insert_data.

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

Anda akan melihat:

Inserted data

Catatan: Ada batasan untuk ukuran commit. Lihat batas CRUD untuk mengetahui informasi selengkapnya.

Membuat kueri data menggunakan SQL

Spanner mendukung antarmuka SQL untuk membaca data, yang dapat Anda akses di command line menggunakan Google Cloud CLI atau secara terprogram menggunakan library klien Spanner untuk Ruby.

Di command line

Jalankan pernyataan SQL berikut untuk membaca nilai semua kolom dari tabel Albums:

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

Catatan: Untuk referensi GoogleSQL, lihat Sintaksis kueri di GoogleSQL dan untuk referensi PostgreSQL, lihat Struktur dan sintaksis leksikal PostgreSQL.

Hasilnya adalah:

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

Menggunakan library klien Spanner untuk Ruby

Selain menjalankan pernyataan SQL di command line, Anda dapat mengeluarkan pernyataan SQL yang sama secara terprogram menggunakan library klien Spanner untuk Ruby.

Gunakan metode Client#execute untuk menjalankan kueri SQL. Gunakan simbol Ruby :ColumnName untuk mengakses data untuk kolom tertentu dari baris.

Berikut cara mengeluarkan kueri dan mengakses data:

# 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

Jalankan sampel menggunakan argumen query_data.

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

Anda akan melihat hasil berikut:

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

Membuat kueri menggunakan parameter SQL

Jika aplikasi Anda memiliki kueri yang sering dijalankan, Anda dapat meningkatkan performanya dengan memparameterisasinya. Kueri parametrik yang dihasilkan dapat di-cache dan digunakan kembali, yang mengurangi biaya kompilasi. Untuk mengetahui informasi selengkapnya, lihat Menggunakan parameter kueri untuk mempercepat kueri yang sering dijalankan.

Berikut adalah contoh penggunaan parameter dalam klausa WHERE untuk mengkueri data yang berisi nilai tertentu untuk 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

Jalankan contoh menggunakan argumen query_with_parameter.

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

Anda akan melihat hasil berikut:

12 Melissa Garcia

Membaca data menggunakan read API

Selain antarmuka SQL Spanner, Spanner juga mendukung antarmuka baca.

Gunakan metode Client#read dari class Client untuk membaca baris dari database.

Berikut cara membaca data:

# 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

Jalankan sampel menggunakan argumen read_data.

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

Anda akan melihat output yang mirip dengan:

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

Memperbarui skema database

Misalkan Anda perlu menambahkan kolom baru bernama MarketingBudget ke tabel Albums. Menambahkan kolom baru ke tabel yang sudah ada memerlukan pembaruan pada skema database Anda. Spanner mendukung update skema ke database saat database terus melayani traffic. Pembaruan skema tidak memerlukan database offline dan tidak mengunci seluruh tabel atau kolom; Anda dapat terus menulis data ke database selama pembaruan skema. Baca selengkapnya tentang pembaruan skema yang didukung dan performa perubahan skema di Melakukan pembaruan skema.

Menambahkan kolom

Anda dapat menambahkan kolom di command line menggunakan Google Cloud CLI atau secara terprogram menggunakan library klien Spanner untuk Ruby.

Di command line

Gunakan perintah ALTER TABLE berikut untuk menambahkan kolom baru ke tabel:

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'

Anda akan melihat:

Schema updating...done.

Menggunakan library klien Spanner untuk Ruby

Gunakan metode Database#update dari class Database untuk mengubah skema:

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

Jalankan sampel menggunakan argumen add_column.

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

Anda akan melihat:

Added the MarketingBudget column

Menulis data ke kolom baru

Kode berikut menulis data ke kolom baru. Tindakan ini menetapkan MarketingBudget ke 100000 untuk baris yang dikunci oleh Albums(1, 1) dan ke 500000 untuk baris yang dikunci oleh 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"

Jalankan sampel menggunakan argumen update_data.

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

Anda akan melihat:

Updated data

Anda juga dapat menjalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.

Berikut kode untuk menjalankan kueri:

# 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

Untuk menjalankan kueri ini, jalankan sampel menggunakan argumen query_data_with_new_column.

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

Anda akan melihat:

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

Memperbarui data

Anda dapat memperbarui data menggunakan DML dalam transaksi baca-tulis.

Anda menggunakan metode execute_update() untuk menjalankan pernyataan 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"

Jalankan sampel menggunakan argumen write_with_transaction_using_dml.

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

Anda akan melihat:

Transaction complete

Catatan: Anda juga dapat memperbarui data menggunakan mutasi.

Menggunakan indeks sekunder

Misalnya, Anda ingin mengambil semua baris Albums yang memiliki nilai AlbumTitle dalam rentang tertentu. Anda dapat membaca semua nilai dari kolom AlbumTitle menggunakan pernyataan SQL atau panggilan baca, lalu menghapus baris yang tidak memenuhi kriteria, tetapi pemindaian tabel lengkap ini mahal, terutama untuk tabel dengan banyak baris. Sebagai gantinya, Anda dapat mempercepat pengambilan baris saat mencari menurut kolom non-kunci primer dengan membuat indeks sekunder pada tabel.

Menambahkan indeks sekunder ke tabel yang ada memerlukan pembaruan skema. Seperti update skema lainnya, Spanner mendukung penambahan indeks saat database terus melayani traffic. Spanner akan otomatis mengisi ulang indeks dengan data yang ada. Pengisian ulang mungkin memerlukan waktu beberapa menit untuk selesai, tetapi Anda tidak perlu menghentikan database atau menghindari penulisan ke tabel yang diindeks selama proses ini. Untuk mengetahui detail selengkapnya, lihat Menambahkan indeks sekunder.

Setelah Anda menambahkan indeks sekunder, Spanner akan otomatis menggunakannya untuk kueri SQL yang kemungkinan akan berjalan lebih cepat dengan indeks tersebut. Jika menggunakan antarmuka baca, Anda harus menentukan indeks yang ingin digunakan.

Menambahkan indeks sekunder

Anda dapat menambahkan indeks di command line menggunakan gcloud CLI atau secara terprogram menggunakan library klien Spanner untuk Ruby.

Di command line

Gunakan perintah CREATE INDEX berikut untuk menambahkan indeks ke database:

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

Anda akan melihat:

Schema updating...done.

Menggunakan library klien Spanner untuk Ruby

Gunakan metode Database#update class Database untuk menambahkan indeks:

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

Jalankan sampel menggunakan argumen create_index.

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

Menambahkan indeks dapat memerlukan waktu beberapa menit. Setelah indeks ditambahkan, Anda akan melihat:

Added the AlbumsByAlbumTitle index

Membaca menggunakan indeks

Untuk kueri SQL, Spanner otomatis menggunakan indeks yang sesuai. Di antarmuka baca, Anda harus menentukan indeks dalam permintaan.

Untuk menggunakan indeks di antarmuka baca, berikan parameter index ke metode read dari class 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

Jalankan sampel menggunakan argumen read_data_with_index.

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

Anda akan melihat:

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

Menambahkan indeks untuk pembacaan khusus indeks

Anda mungkin telah memperhatikan bahwa contoh baca sebelumnya tidak menyertakan pembacaan kolom MarketingBudget. Hal ini karena antarmuka baca Spanner tidak mendukung kemampuan untuk menggabungkan indeks dengan tabel data guna mencari nilai yang tidak disimpan dalam indeks.

Buat definisi alternatif AlbumsByAlbumTitle yang menyimpan salinan MarketingBudget dalam indeks.

Di command line

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)

Menambahkan indeks dapat memerlukan waktu beberapa menit. Setelah indeks ditambahkan, Anda akan melihat:

Schema updating...done.

Menggunakan library klien Spanner untuk Ruby

Gunakan metode Database#update dari class Database untuk menambahkan indeks dengan klausa 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"

Jalankan sampel menggunakan argumen create_storing_index.

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

Anda akan melihat:

Added the AlbumsByAlbumTitle2 index

Sekarang Anda dapat menjalankan operasi baca yang mengambil semua kolom AlbumId, AlbumTitle, dan MarketingBudget dari indeks 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

Jalankan sampel menggunakan argumen read_data_with_storing_index.

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

Anda akan melihat output yang mirip dengan:

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

Mengambil data menggunakan transaksi hanya baca

Misalkan Anda ingin menjalankan lebih dari satu pembacaan pada stempel waktu yang sama. Transaksi hanya baca mengamati awalan yang konsisten dari histori commit transaksi, sehingga aplikasi Anda selalu mendapatkan data yang konsisten. Gunakan objek Snapshot untuk menjalankan transaksi hanya baca. Gunakan metode snapshot dari class Client untuk mendapatkan objek Snapshot.

Berikut cara menjalankan kueri dan melakukan pembacaan dalam transaksi hanya baca yang sama:

# 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

Jalankan sampel menggunakan argumen read_only_transaction.

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

Anda akan melihat output yang mirip dengan:

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

Pembersihan

Agar tidak menimbulkan biaya tambahan pada akun Penagihan Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus database dan hapus instance yang Anda buat.

Menghapus database

Jika Anda menghapus instance, semua database di dalamnya akan otomatis dihapus. Langkah ini menunjukkan cara menghapus database tanpa menghapus instance (Anda tetap dikenai biaya untuk instance tersebut).

Di command line

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

Menggunakan Google Cloud console

1. Buka halaman Spanner Instances di konsol Google Cloud .

   Buka halaman Instances

2. Klik instance.

3. Klik database yang ingin Anda hapus.

4. Di halaman Database details, klik Delete.

5. Konfirmasi bahwa Anda ingin menghapus database, lalu klik Hapus.

Menghapus instance

Menghapus instance akan otomatis menghapus semua database yang dibuat di instance tersebut.

Di command line

gcloud spanner instances delete test-instance

Menggunakan Google Cloud console

1. Buka halaman Spanner Instances di konsol Google Cloud .

   Buka halaman Instances

2. Klik instance Anda.

3. Klik Hapus.

4. Konfirmasi bahwa Anda ingin menghapus instance, lalu klik Hapus.

Langkah berikutnya

• Pelajari cara mengakses Spanner dengan instance virtual machine.

• Pelajari kredensial otorisasi dan autentikasi di Mengautentikasi ke layanan Cloud menggunakan library klien.

• Pelajari lebih lanjut Praktik terbaik desain skema Spanner.