Tujuan
Tutorial ini akan memandu Anda melakukan langkah-langkah berikut menggunakan library klien Spanner untuk Python:
- Membuat instance dan database Spanner.
- Menulis, membaca, dan menjalankan kueri SQL pada data dalam database.
- Memperbarui skema database.
- Mengupdate data menggunakan transaksi baca-tulis.
- Menambahkan 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 Penyiapan, yang mencakup pembuatan dan penetapan project Google Cloud default, mengaktifkan penagihan, mengaktifkan Cloud Spanner API, dan menyiapkan OAuth 2.0 untuk mendapatkan kredensial autentikasi guna menggunakan Cloud Spanner API.
Secara khusus, pastikan Anda menjalankan gcloud auth
application-default login
untuk menyiapkan lingkungan pengembangan lokal dengan kredensial
autentikasi.
Menyiapkan lingkungan Python lokal Anda
Ikuti petunjuk di Menyiapkan Lingkungan Pengembangan Python.
Buat clone repositori aplikasi contoh ke komputer lokal Anda:
git clone https://github.com/googleapis/google-cloud-python.gitAtau, Anda dapat mendownload sampel sebagai file ZIP dan mengekstraknya.
Ubah ke direktori yang berisi kode contoh Spanner:
cd google-cloud-python/packages/google-cloud-spanner/samples/samplesBuat lingkungan Python yang terisolasi, dan instal dependensi:
python3 -m venv env source env/bin/activate pip install -r requirements.txt
Membuat instance
Saat pertama kali menggunakan Spanner, Anda harus membuat instance, yaitu alokasi resource yang digunakan oleh database Spanner. Saat membuat instance, Anda memilih konfigurasi instance, yang menentukan tempat data Anda disimpan, serta jumlah node yang akan digunakan, yang menentukan jumlah resource penyajian dan penyimpanan dalam instance Anda.
Lihat Membuat instance
untuk mempelajari cara membuat instance Spanner menggunakan salah satu
metode berikut. Anda dapat memberi nama instance Anda test-instance untuk menggunakannya dengan topik lain dalam dokumen ini yang mereferensikan instance bernama test-instance.
- Google Cloud CLI
- Konsol Google Cloud
- Library klien (C++, C#, Go, Java, Node.js, PHP, Python, Ruby, atau Rust)
Melihat contoh file
Repositori contoh berisi contoh yang menunjukkan cara menggunakan Spanner dengan Python.
Lihat filesnippets.py, yang menunjukkan cara menggunakan Spanner. Kode ini menunjukkan cara membuat dan menggunakan database baru. Data ini menggunakan contoh skema yang ditampilkan di halaman Skema dan model data.
Buat database
GoogleSQL
python snippets.py test-instance --database-id example-db create_database
PostgreSQL
python pg_snippets.py test-instance --database-id example-db create_database
Anda akan melihat:
Created database example-db on instance test-instance
GoogleSQL
PostgreSQL
Langkah berikutnya adalah menulis data ke database Anda.
Membuat klien database
Sebelum dapat melakukan pembacaan atau penulisan, Anda harus membuatClient. Anda dapat menganggap Client sebagai koneksi database: semua interaksi Anda dengan Spanner harus melalui Client. Biasanya, Anda membuat Client saat
aplikasi dimulai, lalu menggunakan kembali Client tersebut untuk membaca, menulis, dan
mengeksekusi transaksi. Kode berikut menunjukkan cara membuat klien.
Baca selengkapnya di 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.
Jalankan contoh menggunakan argumen insert_with_dml.
python snippets.py test-instance --database-id example-db insert_with_dml
Anda akan melihat:
4 record(s) inserted.
Menulis data dengan mutasi
Anda juga dapat menyisipkan data menggunakan mutasi.
Anda menulis data menggunakan objek
Batch. Objek Batch adalah penampung untuk operasi mutasi. Mutasi
mewakili urutan penyisipan, pembaruan, dan penghapusan yang diterapkan Spanner
secara atomik ke berbagai baris dan tabel dalam database Spanner.
Metode
insert()
di class Batch menambahkan satu atau beberapa mutasi penyisipan ke
batch. Semua mutasi dalam satu batch diterapkan secara atomik.
Kode ini menunjukkan cara menulis data menggunakan mutasi:
Jalankan contoh menggunakan argumen insert_data.
python snippets.py test-instance --database-id example-db insert_data
Anda akan melihat:
Inserted data.
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 Python.
Di command line
Jalankan pernyataan SQL berikut untuk membaca nilai semua kolom dari tabel Albums:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Sintaksis Pipe GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='FROM Albums |> SELECT SingerId, AlbumId, AlbumTitle'
Hasilnya menunjukkan:
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 Python
Selain menjalankan pernyataan SQL di command line, Anda dapat mengeluarkan pernyataan SQL yang sama secara terprogram menggunakan library klien Spanner untuk Python.
Gunakan metode
execute_sql()
dari objek
Snapshot untuk
menjalankan kueri SQL. Untuk mendapatkan objek Snapshot, panggil metode
snapshot()
dari class Database
dalam pernyataan with.
Berikut cara mengeluarkan kueri dan mengakses data:
Jalankan contoh menggunakan argumen query_data.
python snippets.py test-instance --database-id example-db query_data
Anda akan melihat hasil berikut:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Membuat kueri menggunakan parameter SQL
Jika aplikasi Anda memiliki kueri yang sering dieksekusi, Anda dapat meningkatkan performanya dengan membuat parameter. Kueri parametrik yang dihasilkan dapat di-cache dan digunakan kembali, sehingga 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.
GoogleSQL
PostgreSQL
Jalankan contoh menggunakan argumen query_data_with_parameter.
GoogleSQL
python snippets.py test-instance --database-id example-db query_data_with_parameter
PostgreSQL
python pg_snippets.py test-instance --database-id example-db query_data_with_parameter
Anda akan melihat hasil berikut:
SingerId: 12, FirstName: Melissa, LastName: Garcia
Membaca data menggunakan read API
Selain antarmuka SQL Spanner, Spanner juga mendukung antarmuka baca.
Gunakan metode read()
dari objek Snapshot
untuk membaca baris dari database. Untuk mendapatkan objek Snapshot, panggil metode
snapshot()
dari class Database
dalam pernyataan with. Gunakan objek KeySet
untuk menentukan kumpulan kunci dan rentang kunci yang akan dibaca.
Berikut cara membaca data:
Jalankan contoh menggunakan argumen read_data.
python snippets.py test-instance --database-id example-db read_data
Anda akan melihat output yang mirip dengan:
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
Memperbarui skema database
Asumsikan Anda perlu menambahkan kolom baru bernama MarketingBudget ke tabel Albums. Menambahkan kolom baru ke tabel yang ada memerlukan pembaruan pada skema database Anda. Spanner mendukung pembaruan skema ke database saat database terus melayani traffic. Pembaruan skema tidak memerlukan penghentian database dan tidak mengunci seluruh tabel atau kolom; Anda dapat terus menulis data ke database selama pembaruan skema. Baca selengkapnya tentang update skema yang didukung dan performa perubahan skema di Membuat update skema.
Menambahkan kolom
Anda dapat menambahkan kolom di command line menggunakan Google Cloud CLI atau secara terprogram menggunakan library klien Spanner untuk Python.
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 Python
Gunakan metodeupdate_ddl()
dari class Database
untuk mengubah skema:
GoogleSQL
PostgreSQL
Jalankan contoh menggunakan argumen add_column.
GoogleSQL
python snippets.py test-instance --database-id example-db add_column
PostgreSQL
python pg_snippets.py test-instance --database-id example-db add_column
Anda akan melihat:
Added the MarketingBudget column.
Menulis data ke kolom baru
Kode berikut menulis data ke kolom baru. Ini menetapkan MarketingBudget ke
100000 untuk row key Albums(1, 1) dan ke 500000 untuk row key
Albums(2, 2).
Jalankan contoh menggunakan argumen update_data.
python snippets.py test-instance --database-id example-db update_data
Anda juga dapat menjalankan kueri SQL atau panggilan baca untuk mengambil nilai yang baru saja Anda tulis.
Berikut kode untuk menjalankan kueri:
Untuk mengeksekusi kueri ini, jalankan contoh menggunakan argumen query_data_with_new_column.
python snippets.py test-instance --database-id example-db query_data_with_new_column
Anda akan melihat:
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 1, AlbumId: 2, MarketingBudget: None
SingerId: 2, AlbumId: 1, MarketingBudget: None
SingerId: 2, AlbumId: 3, MarketingBudget: None
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
Memperbarui data
Anda dapat memperbarui data menggunakan DML dalam transaksi baca-tulis.
Anda menggunakan metode execute_update() untuk menjalankan pernyataan DML.
Jalankan contoh menggunakan argumen write_with_dml_transaction.
python snippets.py test-instance --database-id example-db write_with_dml_transaction
Anda akan melihat:
Transferred 200000 from Album2's budget to Album1's
Menggunakan indeks sekunder
Misalkan 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. Namun, melakukan pemindaian tabel penuh ini mahal, terutama untuk tabel dengan banyak baris. Sebagai gantinya, Anda dapat mempercepat pengambilan baris saat melakukan penelusuran berdasarkan kolom kunci non-primer dengan membuat indeks sekunder pada tabel.
Menambahkan indeks sekunder ke tabel yang ada memerlukan pembaruan skema. Seperti pembaruan skema lainnya, Spanner mendukung penambahan indeks saat database terus melayani traffic. Spanner otomatis mengisi ulang indeks dengan data yang ada. Pengisian ulang mungkin memerlukan waktu beberapa menit, 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 Python.
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 Python
Gunakan metodeupdate_ddl()
dari class Database
untuk menambahkan indeks:
Jalankan contoh menggunakan argumen add_index.
python snippets.py test-instance --database-id example-db add_index
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 argumen Index ke metode read() dari objek Snapshot. Untuk mendapatkan objek Snapshot, panggil
metode snapshot() dari
class Database dalam pernyataan with.
Jalankan contoh menggunakan argumen read_data_with_index.
python snippets.py test-instance --database-id example-db read_data_with_index
Anda akan melihat:
AlbumId: 2, AlbumTitle: Forever Hold Your Peace
AlbumId: 2, AlbumTitle: Go, Go, Go
AlbumId: 1, AlbumTitle: Green
AlbumId: 3, AlbumTitle: Terrified
AlbumId: 1, AlbumTitle: Total Junk
Menambahkan indeks untuk pembacaan khusus indeks
Anda mungkin telah memperhatikan bahwa contoh pembacaan sebelumnya tidak menyertakan pembacaan kolom MarketingBudget. Hal ini disebabkan oleh antarmuka baca Spanner yang 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 di 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 Python
Gunakan metodeupdate_ddl()
dari class Database
untuk menambahkan indeks dengan klausa STORING:
Jalankan contoh menggunakan argumen add_storing_index.
python snippets.py test-instance --database-id example-db add_storing_index
Anda akan melihat:
Added the AlbumsByAlbumTitle2 index.
Sekarang Anda dapat menjalankan pembacaan yang mengambil semua kolom AlbumId, AlbumTitle, dan
MarketingBudget dari indeks AlbumsByAlbumTitle2:
Jalankan contoh menggunakan argumen read_data_with_storing_index.
python snippets.py test-instance --database-id example-db read_data_with_storing_index
Anda akan melihat output yang mirip dengan:
AlbumId: 2, AlbumTitle: Forever Hold Your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: None
AlbumId: 1, AlbumTitle: Green, MarketingBudget: None
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: None
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 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. Untuk mendapatkan objek Snapshot, panggil metode
snapshot()
dari class Database
dalam pernyataan with.
Berikut ini menunjukkan cara menjalankan kueri dan melakukan pembacaan dalam transaksi hanya baca yang sama:
Jalankan contoh menggunakan argumen read_only_transaction.
python snippets.py test-instance --database-id example-db read_only_transaction
Anda akan melihat output yang mirip dengan:
Results from first read:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Results from second read:
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
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 akan tetap dikenai biaya untuk instance tersebut).
Di command line
gcloud spanner databases delete example-db --instance=test-instance
Menggunakan konsol Google Cloud
Buka halaman Spanner Instances di konsol Google Cloud .
Klik instance.
Klik database yang ingin Anda hapus.
Di halaman Database details, klik Delete.
Konfirmasi bahwa Anda ingin menghapus database, lalu klik Delete.
Menghapus instance
Menghapus instance akan otomatis menghapus semua database yang dibuat di instance tersebut.
Di command line
gcloud spanner instances delete test-instance
Menggunakan konsol Google Cloud
Buka halaman Spanner Instances di konsol Google Cloud .
Klik instance Anda.
Klik Hapus.
Konfirmasi bahwa Anda ingin menghapus instance, lalu klik Delete.
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.