Beberapa atau semua informasi di halaman ini mungkin tidak berlaku untuk Trusted Cloud oleh S3NS.

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 fitur ini, 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 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 update 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. Tabel ini 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 Anda, 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 Anda membuat koneksi, buka koneksi tersebut, lalu 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 koneksi baru akses baca ke instance atau database Spanner. Sebaiknya gunakan peran IAM bawaan 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 Instances Spanner.

Buka halaman instance
Klik nama instance yang berisi database Anda untuk membuka halaman Instance details.
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 konsol Trusted Cloud .

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 Jenis lokasi, 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 External source, 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
  - Atau, untuk Peran database, masukkan nama peran database Spanner. Untuk mengetahui informasi selengkapnya, baca tentang Peran database yang digunakan untuk membuat Koneksi Spanner
  - Atau, centang kotak di samping Gunakan koneksi Resource Cloud untuk membuat set data eksternal dengan koneksi.
- Biarkan setelan default lainnya seperti apa adanya.
Klik Create dataset.

SQL

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

Di Trusted 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 yang memenuhi syarat dan lengkap, 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 mengetahui informasi selengkapnya tentang cara menjalankan kueri, lihat artikel 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 yang memenuhi syarat dan lengkap, 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 mengetahui 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 Trusted Cloud , selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

Luncurkan Cloud Shell.
Tetapkan project default Trusted Cloud 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 Trusted Cloud project Anda untuk melihat hasilnya. Di konsol Trusted 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 pokok. Koneksi resource Cloud yang terkait dengan akun layanan digunakan untuk terhubung ke Spanner. Pengguna dapat membuat kueri 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 modifikasi 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 dalam 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 bernama tidak didukung.
Kunci utama dan kunci asing yang ditentukan dalam database Spanner tidak terlihat di BigQuery.
Jika tabel dalam database Spanner berisi kolom dengan 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 dalam set data eksternal Spanner.
Tampilan INFORMATION_SCHEMA tidak didukung.
Penyimpanan dalam cache metadata tidak didukung.
Setelan tingkat set data yang terkait dengan 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 Dataplex Universal Catalog tidak didukung. Misalnya, profil data dan pemindaian kualitas data tidak didukung.
Tag di tingkat tabel tidak didukung.
Penyelesaian otomatis SQL tidak berfungsi dengan tabel eksternal Spanner saat Anda menulis kueri.
Pindai dengan Sensitive Data Protection 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.