Tujuan
Tutorial ini memandu Anda melakukan langkah-langkah berikut menggunakan Cloud Spanner API dengan REST:
- Membuat instance dan database Spanner.
- Menulis, membaca, dan menjalankan kueri SQL pada data dalam database.
- Perbarui skema database.
- Tambahkan indeks sekunder ke database.
- Menggunakan indeks untuk membaca dan mengeksekusi kueri SQL pada data.
- Mengambil data menggunakan transaksi hanya baca.
Jika Anda ingin menggunakan library klien Spanner dan bukan REST API, lihat Tutorial.
Biaya
Tutorial ini menggunakan Spanner, yang merupakan komponen Google Cloud yang dapat ditagih. Untuk mengetahui informasi tentang biaya penggunaan Spanner, lihat Harga.
Sebelum memulai
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.
-
Make sure that billing is enabled for your Google Cloud project.
-
Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.
-
Make sure that billing is enabled for your Google Cloud project.
Cara melakukan panggilan REST
Anda dapat melakukan panggilan REST Spanner menggunakan:
- Fitur Coba! yang ada dalam dokumentasi referensi Spanner API. Contoh yang ditampilkan di halaman ini menggunakan fitur Coba!.
- Google APIs Explorer, yang berisi Cloud Spanner API dan Google API lainnya.
- Alat atau framework lain yang mendukung panggilan REST HTTP.
Konvensi yang digunakan di halaman ini
Contoh tersebut menggunakan
[PROJECT_ID]
sebagai project ID Google Cloud. Ganti ID project Google Cloud Anda untuk[PROJECT_ID]
. (Jangan sertakan[
dan]
dalam project ID Anda.)Contoh tersebut membuat dan menggunakan ID instance
test-instance
. Ganti ID instance jika Anda tidak menggunakantest-instance
.Contoh tersebut membuat dan menggunakan ID database
example-db
. Ganti ID database jika Anda tidak menggunakanexample-db
.Contoh ini menggunakan
[SESSION]
sebagai bagian dari nama sesi. Ganti nilai yang Anda terima saat membuat sesi untuk[SESSION]
. (Jangan sertakan[
dan]
dalam nama sesi Anda.)Contoh menggunakan ID transaksi
[TRANSACTION_ID]
. Ganti nilai yang Anda terima saat membuat transaksi untuk[TRANSACTION_ID]
. (Jangan sertakan[
dan]
dalam ID transaksi Anda.)Fungsi Try-It! mendukung penambahan kolom permintaan HTTP satu per satu secara interaktif. Sebagian besar contoh dalam topik ini menyediakan keseluruhan permintaan, bukan menjelaskan cara menambahkan masing-masing kolom secara interaktif ke permintaan.
Instance
Saat pertama kali menggunakan Spanner, Anda harus membuat instance, yang merupakan alokasi resource yang digunakan oleh database Spanner. Saat membuat instance, Anda memilih tempat data disimpan dan berapa banyak kapasitas komputasi yang dimiliki instance.
Mencantumkan konfigurasi instance
Saat membuat instance, Anda menentukan konfigurasi instance, yang menentukan penempatan geografis dan replikasi database Anda dalam instance tersebut. Anda dapat memilih konfigurasi regional, yang menyimpan data di satu region, atau konfigurasi multi-region, yang mendistribusikan data di beberapa region. Pelajari lebih lanjut di Instance.
Gunakan projects.instanceConfigs.list
untuk menentukan konfigurasi yang tersedia untuk project Google Cloud Anda.
- Klik
projects.instanceConfigs.list
. Untuk parent, masukkan:
projects/[PROJECT_ID]
Klik Jalankan. Konfigurasi instance yang tersedia ditampilkan dalam respons. Berikut ini contoh respons (project Anda mungkin memiliki konfigurasi instance yang berbeda):
{ "instanceConfigs": [ { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-south1", "displayName": "asia-south1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-east1", "displayName": "asia-east1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-asia-northeast1", "displayName": "asia-northeast1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-europe-west1", "displayName": "europe-west1" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-us-east4", "displayName": "us-east4" }, { "name": "projects/[PROJECT_ID]/instanceConfigs/regional-us-central1", "displayName": "us-central1" } ] }
Anda menggunakan nilai name
untuk salah satu konfigurasi instance saat membuat instance.
Membuat instance
- Klik
projects.instances.create
. Untuk parent, masukkan:
projects/[PROJECT_ID]
Klik Tambahkan parameter isi permintaan, lalu pilih
instance
.Klik balon petunjuk untuk instance guna melihat kemungkinan kolom. Tambahkan nilai untuk kolom berikut:
nodeCount
: Masukkan1
.config
: Masukkan nilainame
dari salah satu konfigurasi instance regional yang ditampilkan saat Anda mencantumkan konfigurasi instance.displayName
: MasukkanTest Instance
.
Klik balon petunjuk yang mengikuti tanda kurung tutup untuk instance lalu pilih instanceId.
Untuk
instanceId
, masukkantest-instance
.
Halaman pembuatan instance Coba! sekarang akan terlihat seperti ini:Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Anda dapat mencantumkan instance menggunakan
projects.instances.list
.
Buat database
Buat database bernama example-db
.
- Klik
projects.instances.databases.create
. Untuk parent, masukkan:
projects/[PROJECT_ID]/instances/test-instance
Klik Tambahkan parameter isi permintaan, lalu pilih
createStatement
.Untuk
createStatement
, masukkan:CREATE DATABASE `example-db`
(Nama database,
example-db
, berisi tanda hubung, sehingga harus diapit dengan tanda kutip tunggal (`
).Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Anda dapat mencantumkan database menggunakan
projects.instances.databases.list
.
Membuat skema
Gunakan Data Definition Language (DDL) Spanner untuk membuat, mengubah, atau menghapus tabel, dan untuk membuat atau menghapus indeks.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan parameter berikut:
{ "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" ] }
Array
statements
berisi pernyataan DDL yang menentukan skema.Klik Jalankan. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Skema ini menentukan dua tabel, Singers
dan Albums
, untuk aplikasi musik
dasar. Tabel tersebut digunakan di seluruh halaman ini. Lihat skema contoh jika Anda belum melakukannya.
Anda dapat mengambil skema menggunakan
projects.instances.databases.getDdl
.
Membuat sesi
Agar dapat menambahkan, memperbarui, menghapus, atau membuat kueri data, Anda harus membuat sesi, yang mewakili saluran komunikasi dengan layanan database Spanner. (Anda tidak menggunakan sesi secara langsung jika menggunakan library klien Spanner, karena library klien mengelola sesi untuk Anda.)
- Klik
projects.instances.databases.sessions.create
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Klik Jalankan.
Respons akan menampilkan sesi yang Anda buat, dalam bentuk
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Anda akan menggunakan sesi ini saat membaca atau menulis ke database.
Sesi dimaksudkan untuk berlangsung lama. Layanan database Spanner dapat
menghapus sesi jika sesi tidak ada aktivitas selama lebih dari satu jam. Upaya untuk menggunakan hasil sesi yang dihapus akan menghasilkan NOT_FOUND
. Jika Anda mengalami error ini, buat
dan gunakan sesi baru. Anda dapat melihat apakah sesi masih aktif menggunakan
projects.instances.databases.sessions.get
.
Untuk informasi terkait, lihat Membuat sesi tidak ada aktivitas tetap aktif.
Langkah selanjutnya adalah menulis data ke database Anda.
Menulis data
Anda menulis data menggunakan
jenis
Mutation
. Mutation
adalah penampung untuk operasi mutasi. Mutation
mewakili urutan penyisipan, pembaruan, penghapusan, dan tindakan lainnya yang dapat
diterapkan secara atomik ke berbagai baris dan tabel di
database Spanner.
- Klik
projects.instances.databases.sessions.commit
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "insertOrUpdate": { "table": "Singers", "columns": [ "SingerId", "FirstName", "LastName" ], "values": [ [ "1", "Marc", "Richards" ], [ "2", "Catalina", "Smith" ], [ "3", "Alice", "Trentor" ], [ "4", "Lea", "Martin" ], [ "5", "David", "Lomond" ] ] } }, { "insertOrUpdate": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "values": [ [ "1", "1", "Total Junk" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "2", "Forever Hold Your Peace" ], [ "2", "3", "Terrified" ] ] } } ] }
Klik Jalankan. Respons menunjukkan stempel waktu commit.
Contoh ini menggunakan insertOrUpdate
. operations lainnya
untuk Mutations
adalah insert
, update
, replace
, dan delete
.
Untuk informasi tentang cara mengenkode jenis data, lihat TypeCode.
Membuat kueri data menggunakan SQL
- Klik
projects.instances.databases.sessions.executeSql
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums" }
Klik Jalankan. Respons akan menampilkan hasil kueri.
Membaca data menggunakan read API
- Klik
projects.instances.databases.sessions.read
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true } }
Klik Jalankan. Respons akan menampilkan hasil operasi baca.
Memperbarui skema database
Asumsikan Anda perlu menambahkan kolom baru bernama MarketingBudget
ke tabel Albums
, yang memerlukan pembaruan pada skema database Anda. Spanner
mendukung pembaruan skema ke database, sementara database terus melayani
traffic. Update skema tidak memerlukan pembuatan database secara offline dan update tersebut tidak mengunci seluruh tabel atau kolom. Anda dapat terus menulis data ke database selama update skema.
Menambahkan kolom
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan parameter berikut:
{ "statements": [ "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64" ] }
Array
statements
berisi pernyataan DDL yang menentukan skema.Klik Jalankan. Proses ini mungkin memerlukan waktu beberapa menit, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Menulis data ke kolom baru
Kode berikut menulis data ke kolom baru. Fungsi ini menetapkan MarketingBudget
ke
100000
untuk baris yang dikunci oleh Albums(1, 1)
dan 500000
untuk baris yang dikunci
oleh Albums(2, 2)
.
- Klik
projects.instances.databases.sessions.commit
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "singleUseTransaction": { "readWrite": {} }, "mutations": [ { "update": { "table": "Albums", "columns": [ "SingerId", "AlbumId", "MarketingBudget" ], "values": [ [ "1", "1", "100000" ], [ "2", "2", "500000" ] ] } } ] }
Klik Jalankan. Respons menunjukkan stempel waktu commit.
Anda juga dapat menjalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
Berikut adalah cara mengeksekusi kueri:
- Klik
projects.instances.databases.sessions.executeSql
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "sql": "SELECT SingerId, AlbumId, MarketingBudget FROM Albums" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat dua baris berisi nilai
MarketingBudget
yang diupdate:"rows": [ [ "1", "1", "100000" ], [ "1", "2", null ], [ "2", "1", null ], [ "2", "2", "500000" ], [ "2", "3", null ] ]
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 melakukan pemindaian tabel penuh ini mahal, terutama untuk tabel
yang memiliki banyak baris. Sebagai gantinya, Anda dapat mempercepat pengambilan baris saat melakukan penelusuran berdasarkan kolom kunci non-utama dengan membuat indeks sekunder pada tabel.
Menambahkan indeks sekunder ke tabel yang ada memerlukan pembaruan skema. Seperti update skema lainnya, Spanner mendukung penambahan indeks sementara database terus menyalurkan traffic. Spanner secara otomatis mengisi indeks dengan data yang ada. Pengisian ulang mungkin memerlukan waktu beberapa menit untuk diselesaikan, tetapi Anda tidak perlu membuat database menjadi offline atau menghindari penulisan ke tabel atau kolom tertentu selama proses ini. Untuk detail lebih lanjut, lihat pengisian ulang indeks.
Setelah Anda menambahkan indeks sekunder, Spanner akan otomatis menggunakannya untuk kueri SQL yang kemungkinan akan berjalan lebih cepat dengan indeks. Jika menggunakan antarmuka baca, Anda harus menentukan indeks yang ingin digunakan.
Menambahkan indeks sekunder
Anda dapat menambahkan indeks menggunakan updateDdl
.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan parameter berikut:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)" ] }
Klik Jalankan. Proses ini mungkin memerlukan waktu beberapa menit, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Membuat kueri menggunakan indeks
- Klik
projects.instances.databases.sessions.executeSql
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "sql": "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat baris berikut:
"rows": [ [ "2", "Go, Go, Go", null ], [ "2", "Forever Hold Your Peace", "500000" ] ]
Membaca menggunakan indeks
- Klik
projects.instances.databases.sessions.read
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat baris berikut:
"rows": [ [ "2", "Forever Hold Your Peace" ], [ "2", "Go, Go, Go" ], [ "1", "Green" ], [ "3", "Terrified" ], [ "1", "Total Junk" ] ]
Menambahkan indeks dengan klausa STORING
Anda mungkin telah melihat bahwa contoh operasi baca di atas 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.
Anda dapat menambahkan indeks STORING menggunakan updateDdl
.
- Klik
projects.instances.databases.updateDdl
. Untuk database, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Untuk Isi permintaan, gunakan parameter berikut:
{ "statements": [ "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)" ] }
Klik Jalankan. Proses ini mungkin memerlukan waktu beberapa menit, bahkan setelah panggilan REST menampilkan respons. Respons menampilkan operasi yang berjalan lama yang dapat Anda kueri untuk memeriksa statusnya.
Sekarang Anda dapat menjalankan operasi baca yang mengambil semua kolom AlbumId
, AlbumTitle
, dan MarketingBudget
dari indeks AlbumsByAlbumTitle2
:
- Klik
projects.instances.databases.sessions.read
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "table": "Albums", "columns": [ "AlbumId", "AlbumTitle", "MarketingBudget" ], "keySet": { "all": true }, "index": "AlbumsByAlbumTitle2" }
Klik Jalankan. Sebagai bagian dari respons, Anda akan melihat baris berikut:
"rows": [ [ "2", "Forever Hold Your Peace", "500000" ], [ "2", "Go, Go, Go", null ], [ "1", "Green", null ], [ "3", "Terrified", null ], [ "1", "Total Junk", "100000" ] ]
Mengambil data menggunakan transaksi hanya baca
Misalnya Anda ingin mengeksekusi 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.
Membuat transaksi hanya baca
- Klik
projects.instances.databases.sessions.beginTransaction
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
Untuk Isi Permintaan, gunakan:
{ "options": { "readOnly": {} } }
Klik Jalankan.
Respons akan menampilkan ID transaksi yang Anda buat.
Anda kini dapat menggunakan transaksi hanya baca untuk mengambil data pada stempel waktu yang konsisten, meskipun data telah berubah sejak Anda membuat transaksi hanya baca.
Menjalankan kueri menggunakan transaksi hanya baca
- Klik
projects.instances.databases.sessions.executeSql
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "sql": "SELECT SingerId, AlbumId, AlbumTitle FROM Albums", "transaction": { "id": "[TRANSACTION_ID]" } }
Klik Jalankan. Anda akan melihat baris yang mirip dengan berikut ini dalam respons:
"rows": [ [ "2", "2", "Forever Hold Your Peace" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "3", "Terrified" ], [ "1", "1", "Total Junk" ] ]
Membaca menggunakan transaksi hanya baca
- Klik
projects.instances.databases.sessions.read
. Untuk sesi, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/sessions/[SESSION]
(Anda menerima nilai ini saat membuat sesi.)
Untuk Isi permintaan, gunakan parameter berikut:
{ "table": "Albums", "columns": [ "SingerId", "AlbumId", "AlbumTitle" ], "keySet": { "all": true }, "transaction": { "id": "[TRANSACTION_ID]" } }
Klik Jalankan. Anda akan melihat baris yang mirip dengan berikut ini dalam respons:
"rows": [ [ "1", "1", "Total Junk" ], [ "1", "2", "Go, Go, Go" ], [ "2", "1", "Green" ], [ "2", "2", "Forever Hold Your Peace" ], [ "2", "3", "Terrified" ] ]
Spanner juga mendukung transaksi baca-tulis, yang menjalankan serangkaian bacaan dan menulis secara atomik pada satu titik waktu logis. Untuk mengetahui informasi selengkapnya, lihat Transaksi baca-tulis. (Fungsi Try-It! tidak cocok untuk mendemonstrasikan transaksi baca-tulis.)
Pembersihan
Agar tidak menimbulkan biaya tambahan pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus database dan hapus instance yang Anda buat.
Melepaskan database
- Klik
projects.instances.databases.dropDatabase
. Untuk name, masukkan:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db
Klik Jalankan.
Menghapus instance
- Klik
projects.instances.delete
. Untuk name, masukkan:
projects/[PROJECT_ID]/instances/test-instance
Klik Jalankan.
Langkah selanjutnya
- Mengakses Spanner di Instance Virtual Machine: buat instance mesin virtual dengan akses ke database Spanner Anda.
- Pelajari konsep Spanner lebih lanjut.