Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat set data eksternal Spanner

Dokumen ini menjelaskan cara membuat set data eksternal (juga dikenal sebagai set data gabungan) di BigQuery yang ditautkan ke database yang ada di Spanner.

Set data eksternal adalah koneksi antara BigQuery dan sumber data eksternal di tingkat set data. Dengan demikian, Anda dapat membuat kueri data transaksional di database Spanner dengan GoogleSQL tanpa perlu menyalin atau mengimpor semua data dari Spanner ke penyimpanan BigQuery. Hasil kueri ini disimpan di BigQuery.

Tabel dalam set data eksternal secara otomatis diisi dari tabel di sumber data eksternal yang sesuai. Anda dapat membuat kueri tabel ini secara langsung di BigQuery, tetapi Anda tidak dapat membuat modifikasi, penambahan, atau penghapusan. Namun, setiap pembaruan yang Anda lakukan di sumber data eksternal akan otomatis diterapkan di BigQuery.

Saat Anda membuat kueri Spanner, hasil kueri secara default disimpan dalam tabel sementara. Secara opsional, data tersebut juga dapat disimpan sebagai tabel BigQuery baru, digabungkan dengan tabel lain, atau digabungkan dengan tabel yang ada menggunakan DML.

Izin yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat set data eksternal, minta administrator untuk memberi Anda peran IAM BigQuery User (roles/bigquery.user). Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin bigquery.datasets.create, yang diperlukan untuk membuat set data eksternal.

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Untuk mengetahui informasi lebih lanjut tentang peran dan izin IAM di BigQuery, baca Pengantar IAM.

Menggunakan koneksi `CLOUD_RESOURCE`

Secara opsional, set data eksternal Spanner dapat menggunakan koneksi CLOUD_RESOURCE untuk berinteraksi dengan database Spanner, sehingga Anda dapat memberikan akses pengguna ke data Spanner melalui BigQuery, tanpa memberi mereka akses langsung ke database Spanner. Karena akun layanan dari koneksi CLOUD_RESOURCE menangani pengambilan data dari Spanner, Anda hanya perlu memberi pengguna akses ke set data eksternal Spanner.

Sebelum membuat set data eksternal Spanner dengan koneksi CLOUD_RESOURCE, lakukan hal berikut:

Membuat koneksi

Anda dapat membuat atau menggunakan koneksi CLOUD_RESOURCE yang ada untuk terhubung ke Spanner. Untuk membuat koneksi resource Cloud, ikuti langkah-langkah di halaman Membuat koneksi resource Cloud.

Setelah membuat koneksi, buka, dan di panel Connection info, salin ID akun layanan. Anda memerlukan ID ini saat mengonfigurasi izin untuk koneksi. Saat Anda membuat resource koneksi, BigQuery akan membuat akun layanan sistem unik dan mengaitkannya dengan koneksi.

Menyiapkan akses

Anda harus memberikan akses baca koneksi baru ke instance atau database Spanner. Sebaiknya gunakan peran IAM yang telah ditetapkan untuk Cloud Spanner Database Reader dengan DataBoost (roles/spanner.databaseReaderWithDataBoost).

Ikuti langkah-langkah berikut untuk memberikan akses ke peran tingkat database untuk akun layanan yang Anda salin sebelumnya dari koneksi:

Buka halaman Instance Spanner.

Buka halaman instance
Klik nama instance yang berisi database Anda untuk membuka halaman Detail instance.
Di tab Ringkasan, centang kotak untuk database Anda.
Panel info akan muncul.
Klik Tambahkan akun utama.
Di panel Add principals, di New principals, masukkan ID akun layanan yang Anda salin sebelumnya.
Di kolom Select a role, pilih Cloud Spanner Database Reader with DataBoost role.
Klik Simpan.

Membuat set data eksternal

Untuk membuat set data eksternal, lakukan hal berikut:

Konsol

Buka halaman BigQuery di Google Cloud konsol.

Buka halaman BigQuery
Di panel Explorer, pilih project tempat Anda ingin membuat set data.
Luaskan opsi Actions, lalu klik Create dataset.
Di halaman Create dataset, lakukan hal berikut:
- Untuk Dataset ID, masukkan nama set data yang unik.
- Untuk Location type, pilih lokasi untuk set data, seperti us-central1 atau multi-region us. Setelah Anda membuat set data, lokasi tidak dapat diubah.
- Untuk Set Data Eksternal, lakukan hal berikut:
  - Centang kotak di samping Tautkan ke set data eksternal.
  - Untuk Jenis set data eksternal, pilih Spanner.
  - Untuk Sumber eksternal, masukkan ID lengkap database Spanner Anda dalam format berikut: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Misalnya: projects/my_project/instances/my_instance/databases/my_database
  - Secara opsional, untuk Peran database, masukkan nama peran database Spanner. Untuk informasi selengkapnya, baca tentang Peran database yang digunakan untuk membuat Koneksi Spanner
  - Secara opsional, centang kotak di samping Use a Cloud Resource connection untuk membuat set data eksternal dengan koneksi.
- Biarkan setelan default lainnya sebagaimana adanya.
Klik Create dataset.

SQL

Gunakan pernyataan bahasa definisi data (DDL) CREATE EXTERNAL SCHEMA.

Di Google Cloud konsol, buka halaman BigQuery.

Buka BigQuery
Di editor kueri, masukkan pernyataan berikut:
```
CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
/*
  Alternatively, create with a connection:
*/
CREATE EXTERNAL SCHEMA DATASET_NAME
  WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
```
Ganti kode berikut:
- DATASET_NAME: nama set data baru Anda di BigQuery.
- SPANNER_EXTERNAL_SOURCE: nama database Spanner lengkap yang memenuhi syarat, dengan awalan yang mengidentifikasi sumber, dalam format berikut: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Misalnya: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database atau google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
- LOCATION: lokasi set data baru Anda di BigQuery, misalnya, us-central1. Setelah membuat set data, Anda tidak dapat mengubah lokasinya.
- (Opsional)CONNECTION_NAME: nama koneksi resource Cloud Anda.
Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Di lingkungan command line, buat set data eksternal menggunakan perintah bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

Atau, buat dengan koneksi:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

Ganti kode berikut:

LOCATION: lokasi set data baru Anda di BigQuery—misalnya, us-central1. Setelah membuat set data, Anda tidak dapat mengubah lokasinya. Anda dapat menetapkan nilai lokasi default menggunakan file .bigqueryrc.
SPANNER_EXTERNAL_SOURCE: nama database Spanner lengkap yang memenuhi syarat, dengan awalan yang mengidentifikasi sumber, dalam format berikut: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Misalnya: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database atau google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
DATASET_NAME: nama set data baru Anda di BigQuery. Untuk membuat set data dalam project selain project default Anda, tambahkan project ID ke nama set data dalam format berikut: PROJECT_ID:DATASET_NAME.
(Opsional)CONNECTION_NAME: nama koneksi resource Cloud Anda.

Terraform

Gunakan resource google_bigquery_dataset.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Contoh berikut membuat set data eksternal Spanner:

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

Untuk menerapkan konfigurasi Terraform di project Google Cloud , selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

Luncurkan Cloud Shell.
Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

Salin kode contoh ke dalam main.tf yang baru dibuat.

Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.
Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
Simpan perubahan Anda.
Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori.
```
terraform init
```
Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:
```
terraform init -upgrade
```

Menerapkan perubahan

Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:
```
terraform plan
```
Koreksi konfigurasi jika diperlukan.
Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:
```
terraform apply
```
Tunggu hingga Terraform menampilkan pesan "Apply complete!".
Buka Google Cloud project untuk melihat hasilnya. Di konsol Google Cloud , buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

API

Panggil metode datasets.insert dengan resource set data dan kolom externalDatasetReference yang ditentukan untuk database Spanner Anda.

Perhatikan bahwa nama tabel dalam set data eksternal tidak peka huruf besar/kecil.

Saat membuat set data eksternal dengan koneksi CLOUD_RESOURCE, Anda harus memiliki izin bigquery.connections.delegate (tersedia dari peran BigQuery Connection Admin) pada koneksi yang digunakan oleh set data eksternal.

Mengontrol akses ke tabel

Set data eksternal Spanner mendukung kredensial pengguna akhir (EUC). Artinya, akses ke tabel Spanner dari set data eksternal dikontrol oleh Spanner. Pengguna hanya dapat membuat kueri pada tabel ini jika mereka memiliki akses yang diberikan di Spanner.

Set data eksternal Spanner juga mendukung delegasi akses. Delegasi akses memisahkan akses ke tabel Spanner dari set data eksternal dan akses langsung ke tabel Spanner yang mendasarinya. Koneksi resource Cloud yang terkait dengan akun layanan digunakan untuk terhubung ke Spanner. Pengguna dapat membuat kueri pada tabel Spanner ini dari set data eksternal meskipun mereka tidak memiliki akses yang diberikan di Spanner.

Mencantumkan tabel dalam set data eksternal

Untuk mencantumkan tabel yang tersedia untuk kueri dalam set data eksternal Anda, lihat Mencantumkan set data.

Mendapatkan informasi tabel

Untuk mendapatkan informasi tentang tabel dalam set data eksternal, seperti detail skema, lihat Mendapatkan informasi tabel.

Membuat kueri data Spanner

Membuat kueri tabel dalam set data eksternal sama dengan membuat kueri tabel di set data BigQuery lainnya. Namun, operasi perubahan data (DML) tidak didukung.

Kueri terhadap tabel dalam set data eksternal Spanner menggunakan Data Boost secara default dan tidak dapat diubah. Oleh karena itu, Anda memerlukan izin tambahan untuk menjalankan kueri tersebut.

Membuat tampilan dalam set data eksternal

Anda tidak dapat membuat tampilan di set data eksternal. Namun, Anda dapat membuat tampilan dalam set data standar yang didasarkan pada tabel dalam set data eksternal. Untuk mengetahui informasi selengkapnya, lihat Membuat tampilan.

Menghapus set data eksternal

Menghapus set data eksternal sama dengan menghapus set data BigQuery lainnya. Menghapus set data eksternal tidak memengaruhi tabel di database Spanner. Untuk mengetahui informasi selengkapnya, lihat Menghapus set data.

Batasan

Batasan kueri gabungan BigQuery berlaku.
Hanya tabel dari skema Spanner default yang dapat diakses di BigQuery. Tabel dari skema nama tidak didukung.
Kunci utama dan kunci asing yang ditentukan di database Spanner tidak terlihat di BigQuery.
Jika tabel di database Spanner berisi kolom dari jenis yang tidak didukung oleh BigQuery, kolom ini tidak akan dapat diakses di sisi BigQuery.
Anda tidak dapat menambahkan, menghapus, atau memperbarui data atau metadata dalam tabel di set data eksternal Spanner.
Anda tidak dapat membuat tabel, tampilan, atau tampilan terwujud baru di set data eksternal Spanner.
Tampilan INFORMATION_SCHEMA tidak didukung.
Pemcache metadata tidak didukung.
Setelan tingkat set data yang terkait dengan setelan default pembuatan tabel tidak memengaruhi set data eksternal karena Anda tidak dapat membuat tabel secara manual.
Database Spanner yang menggunakan dialek PostgreSQL tidak didukung.
Write API dan Read API tidak didukung.
Keamanan tingkat baris, keamanan tingkat kolom, dan penyamaran data tidak didukung.
Tampilan terwujud berdasarkan tabel dari set data eksternal Spanner tidak didukung.
Integrasi dengan Katalog Universal Dataplex tidak didukung. Misalnya, profil data dan pemindaian kualitas data tidak didukung.
Tag di tingkat tabel tidak didukung.
Pelengkapan otomatis SQL tidak berfungsi dengan tabel eksternal Spanner saat Anda menulis kueri.
Pemindaian dengan Perlindungan Data Sensitif tidak didukung untuk set data eksternal.
Berbagi dengan fitur berbagi BigQuery (sebelumnya Analytics Hub) tidak didukung untuk set data eksternal.
Jika set data eksternal Spanner menggunakan kredensial pengguna akhir (EUC), Anda dapat membuat tampilan yang diotorisasi yang mereferensikan set data eksternal. Namun, saat tampilan ini dikueri, EUC orang yang menjalankan kueri akan dikirim ke Spanner.
Jika set data eksternal Spanner menggunakan koneksi resource Cloud untuk delegasi akses, Anda dapat membuat tampilan yang diotorisasi atau rutinitas yang diotorisasi yang mereferensikan set data eksternal.

Langkah berikutnya

Pelajari lebih lanjut kueri gabungan Spanner.