Menjalankan kueri federasi di Google BigQuery

Halaman ini menjelaskan cara menyiapkan Federasi Lakehouse untuk menjalankan kueri federasi pada data BigQuery yang tidak dikelola oleh Azure Databricks. Untuk mempelajari selengkapnya tentang Federasi Lakehouse, lihat Menyambungkan ke database dan katalog eksternal

Untuk menyambungkan ke database BigQuery Anda menggunakan Federasi Lakehouse, Anda harus membuat yang berikut ini di metastore Azure Databricks Unity Catalog Anda (ruang kerja yang dibuat setelah 9 November 2023 sudah memiliki metastore Katalog Unity yang disediakan secara otomatis):

Koneksi ke database BigQuery Anda.
Katalog asing yang mencerminkan database BigQuery Anda di Unity Catalog sehingga Anda dapat menggunakan sintaks kueri Katalog Unity dan alat tata kelola data untuk mengelola akses pengguna Azure Databricks ke database.

Sebelum Anda mulai

Untuk menjalankan kueri federasi di BigQuery, buat koneksi ke BigQuery dan katalog asing yang mencerminkan database BigQuery Anda. Kemudian Anda dapat mengkueri dan mengelola data BigQuery menggunakan Azure Databricks dan Katalog Unity. Persyaratan izin tambahan ditentukan di setiap bagian berbasis tugas yang berikut.

Persyaratan ruang kerja:

Ruang kerja diaktifkan untuk Katalog Unity.

Persyaratan komputasi:

Konektivitas jaringan dari sumber daya komputasi Anda ke sistem database target. Lihat Rekomendasi jaringan untuk Federasi Lakehouse.
Komputasi Azure Databricks harus menggunakan Databricks Runtime 16.1 atau lebih tinggi serta mode akses standar atau khusus (sebelumnya shared dan single user).
Gudang SQL harus pro atau serverless.

Persyaratan izin:

Untuk membuat koneksi, Anda harus memiliki CREATE CONNECTION privilege pada metastore Katalog Unity yang terhubung dengan ruang kerja.
Untuk membuat katalog asing, Anda harus memiliki izin CREATE CATALOG di metastore dan menjadi pemilik koneksi atau memiliki hak istimewa CREATE FOREIGN CATALOG pada koneksi.

Buat sambungan

Koneksi menentukan jalur dan kredensial untuk mengakses sistem database eksternal. Untuk membuat koneksi, Anda bisa menggunakan Catalog Explorer atau perintah SQL CREATE CONNECTION di buku catatan Azure Databricks atau editor kueri Databricks SQL.

Catatan

Anda juga dapat menggunakan Databricks REST API atau Databricks CLI untuk membuat koneksi. Lihat POST /api/2.1/unity-catalog/connections dan perintah Unity Catalog.

Izin diperlukan: Admin atau pengguna Metastore dengan CREATE CONNECTION hak istimewa.

Penjelajah Katalog

Di ruang kerja Azure Databricks Anda, klik Katalog.
Di bagian atas panel Katalog , klik Tambahkan ikon dan pilih Buat koneksi dari menu.
Di halaman Koneksi dasar-dasar pada wizard Menyiapkan koneksi, masukkan nama Koneksi yang ramah pengguna.
Pilih Jenis koneksi dari Google BigQuery, lalu klik Berikutnya.
Di halaman Autentikasi, masukkan kunci json akun layanan Google untuk instans BigQuery Anda.

Ini adalah objek JSON mentah yang digunakan untuk menentukan proyek BigQuery dan menyediakan autentikasi. Anda dapat membuat objek JSON ini dan mengunduhnya dari halaman detail akun layanan di Google Cloud di bagian 'KEYS'. Akun layanan harus memiliki izin yang tepat yang diberikan di BigQuery, termasuk Pengguna BigQuery dan BigQuery Data Viewer. Berikut adalah contohnya.
```
{
  "type": "service_account",
  "project_id": "PROJECT_ID",
  "private_key_id": "KEY_ID",
  "private_key": "PRIVATE_KEY",
  "client_email": "SERVICE_ACCOUNT_EMAIL",
  "client_id": "CLIENT_ID",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL",
  "universe_domain": "googleapis.com"
}
```
Catatan

Google menetapkan nilai URL di akun layanan JSON, dan nilai tersebut dapat bervariasi menurut akun. Gunakan persis seperti yang muncul di file JSON yang Anda unduh. Jika Anda mengonfigurasi aturan proksi jaringan agar Azure Databricks dapat mengakses API Google, izinkan keduanya: https://accounts.google.com dan https://oauth2.googleapis.com.
(Opsional) Masukkan ID Proyek untuk instans BigQuery Anda:

Ini adalah nama untuk proyek BigQuery yang digunakan untuk penagihan untuk semua kueri yang dijalankan di bawah koneksi ini. Bawaan pada ID proyek dari akun layanan Anda. Akun layanan harus memiliki izin yang tepat yang diberikan untuk proyek ini di BigQuery, termasuk BigQuery User. Himpunan data tambahan yang digunakan untuk menyimpan tabel sementara oleh BigQuery mungkin dibuat dalam proyek ini.
(Opsional) Tambahkan komentar.
Klik Buat koneksi.
Pada halaman dasar-dasar Catalog, masukkan nama untuk katalog asing. Katalog asing mencerminkan database dalam sistem data eksternal sehingga Anda dapat mengkueri dan mengelola akses ke data dalam database tersebut menggunakan Azure Databricks dan Unity Catalog.
(Opsional) Klik Uji koneksi untuk mengonfirmasi bahwa koneksi berfungsi.
Klik Buat katalog.
Pada halaman Access, pilih ruang kerja tempat pengguna dapat mengakses katalog yang Anda buat. Anda dapat memilih Semua ruang kerja memiliki akses, atau klik Tetapkan ke ruang kerja, pilih ruang kerja, lalu klik Tetapkan.
Ubah Pemilik yang akan dapat mengelola akses ke semua objek dalam katalog. Mulai ketik prinsipal dalam kotak teks, lalu klik prinsipal dalam hasil yang dikembalikan.
Berikan Hak Istimewa pada katalog. Klik Pemberian:
1. Tentukan Prinsipal yang akan memiliki akses ke objek dalam katalog. Mulai ketik prinsipal dalam kotak teks, lalu klik prinsipal dalam hasil yang dikembalikan.
2. Pilih preset Privilege untuk diberikan kepada setiap prinsipal. Semua pengguna akun diberikan BROWSE secara default.
  - Pilih Pembaca Data dari menu drop-down untuk memberikan hak akses read pada objek dalam katalog.
  - Pilih Editor Data dari menu drop-down untuk memberikan hak istimewa dan pada objek dalam katalog.
  - Pilih hak istimewa yang akan diberikan secara manual.
3. Klik Berikan.
Klik Berikutnya.
Pada halaman Metadata, tentukan pasangan kunci-nilai tag. Untuk informasi selengkapnya, lihat Menerapkan tag ke objek yang dapat diamankan Katalog Unity.
(Opsional) Tambahkan komentar.
Klik Simpan.

SQL

Jalankan perintah berikut ini di buku catatan atau editor kueri Databricks SQL. Ganti <GoogleServiceAccountKeyJson> dengan objek JSON mentah yang menentukan proyek BigQuery dan menyediakan autentikasi. Anda dapat membuat objek JSON ini dan mengunduhnya dari halaman detail akun layanan di Google Cloud di bagian 'KEYS'. Akun layanan harus memiliki izin yang tepat yang diberikan di BigQuery, termasuk BigQuery User dan BigQuery Data Viewer. Misalnya objek JSON, lihat tab Catalog Explorer di halaman ini.

CREATE CONNECTION <connection-name> TYPE bigquery
OPTIONS (
  GoogleServiceAccountKeyJson '<GoogleServiceAccountKeyJson>'
);

Databricks merekomendasikan agar Anda menggunakan rahasia alih-alih string teks biasa untuk nilai sensitif seperti kredensial. Contohnya:

CREATE CONNECTION <connection-name> TYPE bigquery
OPTIONS (
  GoogleServiceAccountKeyJson secret ('<secret-scope>','<secret-key-user>')
)

Untuk informasi tentang menyiapkan rahasia, lihat Manajemen rahasia.

Membuat katalog asing

Catatan

Jika Anda menggunakan UI untuk membuat koneksi ke sumber data, pembuatan katalog asing disertakan dan Anda dapat melewati langkah ini.

Katalog asing mencerminkan database dalam sistem data eksternal sehingga Anda dapat mengkueri dan mengelola akses ke data dalam database tersebut menggunakan Azure Databricks dan Unity Catalog. Untuk membuat katalog asing, gunakan koneksi ke sumber data yang telah ditentukan.

Untuk membuat katalog asing, Anda bisa menggunakan Catalog Explorer atau CREATE FOREIGN CATALOG di buku catatan Azure Databricks atau editor kueri Databricks SQL. Anda juga dapat menggunakan Databricks REST API atau Databricks CLI untuk membuat katalog. Lihat perintah POST /api/2.1/unity-catalog/catalogs atau Unity Catalog.

Izin yang diperlukan:CREATE CATALOG izin pada metastore dan kepemilikan koneksi atau CREATE FOREIGN CATALOG hak istimewa pada koneksi.

Penjelajah Katalog

Di ruang kerja Azure Databricks Anda, klik Katalog untuk membuka Catalog Explorer.
Di bagian atas panel Katalog , klik ikon Tambahkan atau plustambahkan ikon dan pilih Tambahkan katalog dari menu.

Atau, dari halaman akses cepat, klik tombol Katalog, kemudian klik tombol Buat katalog.
(Opsional) Masukkan properti katalog berikut:

Id Proyek Data: Nama untuk proyek BigQuery yang berisi data yang akan dipetakan ke katalog ini. Secara default ke ID proyek penagihan yang ditetapkan di tingkat koneksi.
Ikuti instruksi untuk membuat katalog asing di Membuat katalog.
(Opsional) Tentukan opsi katalog berikut:
- Materialization Dataset: Nama himpunan data BigQuery opsional yang akan digunakan untuk mewujudkan hasil kueri. Jika tidak ditentukan, himpunan data materialisasi disediakan secara otomatis saat diperlukan. Lihat Materialisasi untuk informasi selengkapnya.
- Force materialization: Apakah hasil akan dimaterialisasi untuk setiap kueri pada katalog. Defaultnya adalah false. Lihat Materialisasi untuk informasi selengkapnya.
- BIGNUMERIC Default Scale: Nilai skala opsional untuk memetakan BigQuery BIGNUMERIC ke Spark DecimalType. Lihat Pemetaan jenis data untuk informasi selengkapnya.

SQL

Jalankan perintah SQL berikut di notebook atau editor SQL Databricks. Item dalam tanda kurung bersifat opsional. Ganti nilai placeholder.

<catalog-name>: Nama untuk katalog di Azure Databricks.
<connection-name>: Objek koneksi yang menentukan sumber data, jalur, dan kredensial akses.
<data-project-id>: ID proyek opsional dari proyek BigQuery yang berisi data yang akan dipetakan ke katalog ini. Jika tidak ditentukan, ID proyek yang ditetapkan pada koneksi digunakan, diikuti oleh ID proyek akun layanan.
<dataset-name>: Nama himpunan data BigQuery opsional yang akan digunakan untuk mewujudkan hasil kueri. Jika tidak ditentukan, himpunan data materialisasi disediakan secara otomatis saat diperlukan. Lihat Materialisasi untuk informasi selengkapnya.
<force-materialization>: Nilai Boolean opsional. Jika true, setiap kueri pada katalog mematerialisasikan hasilnya. Defaultnya adalah false. Lihat Materialisasi untuk informasi selengkapnya.
<scale>: Nilai skala opsional [0, 38] untuk memetakan BigQuery BIGNUMERIC ke Spark DecimalType(38, scale). Defaultnya adalah 38. Lihat Pemetaan jenis data untuk informasi selengkapnya.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
[OPTIONS (
  dataProjectId '<data-project-id>',
  materializationDataset '<dataset-name>',
  forceMaterialization '<force-materialization>',
  bigNumericDefaultScale '<scale>'
)];

Materialisasi

Tidak seperti konektor federasi lainnya, konektor BigQuery menggunakan BIGQuery Storage API alih-alih JDBC untuk meningkatkan performa. Azure Databricks dapat membaca dari BigQuery langsung dari penyimpanan atau menggunakan dataset bermaterialisasi. Pembacaan langsung menawarkan performa yang lebih baik untuk pemindaian besar serta mendukung pushdown filter dan proyeksi. Proses materialisasi mendorong operasi tambahan (pembatasan, agregat, join, pengurutan) ke komputasi BigQuery sebelum hasil dialirkan ke Azure Databricks.

Tampilan dan tabel eksternal selalu dimaterialisasi. Semua operasi baca lainnya menggunakan penyimpanan langsung tanpa materialisasi secara bawaan.

Pertimbangkan untuk mengaktifkan materialisasi jika Anda memerlukan pushdown tingkat lanjut, membaca kumpulan hasil kecil dari himpunan data besar, atau membaca data lintas wilayah. Materialisasi dikenakan biaya komputasi BigQuery tambahan.

Untuk memaksa materialisasi untuk setiap kueri pada katalog asing, pilih Force materialization di Catalog Explorer atau setel opsi katalog forceMaterialization ke true. Anda tidak perlu memperbarui query individual.

forceMaterialization Opsi katalog didukung pada komputasi yang diperlukan, kecuali klaster harus menjalankan Databricks Runtime 16.4 LTS atau lebih tinggi.

Untuk mengaktifkan materialisasi untuk satu kueri, atur opsi materializationEnabled ke true setelah nama tabel BigQuery:

SELECT * FROM <catalog-name>.<schema-name>.<table-name>
WITH ('materializationEnabled' 'true');

Secara default, himpunan data materialisasi disediakan secara otomatis saat diperlukan. Anda dapat menentukan himpunan data kustom menggunakan materializationDataset opsi katalog saat membuat atau mengubah katalog asing. Ini berguna jika akun layanan tidak memiliki izin untuk membuat himpunan data atau jika Anda ingin mengontrol tempat tabel materialisasi sementara disimpan. Contohnya:

CREATE FOREIGN CATALOG my_catalog USING CONNECTION my_bq_connection
OPTIONS (materializationDataset 'my_materialization_dataset');

Untuk memperbarui katalog yang ada, jalankan:

ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Membaca tabel eksternal BigQuery

Anda dapat mengkueri tabel eksternal BigQuery, termasuk bigLake dan tabel yang didukung penyimpanan cloud, langsung dari alur kerja Anda. Tabel ini secara otomatis terwujud sebelum eksekusi kueri, memungkinkan akses penuh ke konten mereka tanpa konfigurasi tambahan.

Tabel eksternal yang didukung

Tabel eksternal BigLake dan Cloud Storage didukung.

Tabel BigLake mereferensikan data yang disimpan dalam penyimpanan cloud dan menyertakan kontrol akses menawan yang dikelola melalui BigQuery.
Tabel eksternal penyimpanan cloud secara langsung mereferensikan file melalui URI.

Saat Anda mengkueri tabel ini, sistem mewujudkan data sehingga kueri Anda berjalan pada penyimpanan BigQuery bawaan untuk dukungan fitur SQL penuh dan performa optimal.

Untuk informasi selengkapnya, lihat dokumentasi BigQuery untuk tabel BigLake dan tabel eksternal Cloud Storage.

Pushdown yang didukung

Dukungan pushdown tergantung pada apakah materialisasi diaktifkan. Beberapa operasi secara otomatis dialihkan ke komputasi BigQuery, sementara yang lain memerlukan materialisasi.

Pushdown berikut ini didukung tanpa perlu materialisasi:

Filter-filter, diterapkan sebagai pembatasan baris API BigQuery Storage (hanya predikat sederhana — perbandingan kolom dengan nilai literal, IN, IS NULL, LIKE, dan kombinasi AND atau OR dari semuanya). Filter yang mereferensikan operator atau fungsi yang tercantum di bawah ini memerlukan materialisasi.
Proyeksi

Pushdown tambahan berikut ini didukung saat materialisasi diaktifkan. Dengan materialisasi, filter dikompilasi ke SQL alih-alih pembatasan baris BIGQuery Storage API, sehingga juga dapat berisi operator dan fungsi berikut:

Batas
Offset, saat digunakan dengan batas
Agregat
Pengurutan, saat digunakan dengan limitasi
Penggabungan (Databricks Runtime 16.1 ke atas)
Operator perbandingan, Boolean, bitwise, dan aritmatika (operator aritmatika hanya mendorong ke bawah saat mode ANSI diaktifkan)
Fungsi matematika (ABS, FLOOR) — dukungan parsial, ekspresi filter saja
Fungsi string (CONCAT, , UPPER, LOWER, LENGTHTRIM, , LTRIM) RTRIM— dukungan parsial, ekspresi filter saja
Contains, Startswith, Endswith
Fungsi tanggal, waktu, dan tanda waktu (DATE_TRUNC, dan EXTRACT untuk tahun, kuartal, bulan, hari, jam, dan menit) — dukungan parsial, ekspresi filter saja
Fungsi lain-lain (COALESCE, , Cast, CASE WHENIF, dan akses elemen array) — dukungan parsial, ekspresi filter saja

Pushdown berikut tidak didukung:

Fungsi jendela

Pemetaan jenis data

Tabel berikut ini memperlihatkan pemetaan jenis data BigQuery ke Spark.

Jenis BigQuery	Tipe Spark
`BIGNUMERIC`, `NUMERIC`	`DecimalType`*
`INT64`	`LongType`
`FLOAT64`	`DoubleType`
`ARRAY`, `GEOGRAPHY`, `INTERVAL`, `JSON`, `STRING`, `STRUCT`	`VarcharType`
`BYTES`	`BinaryType`
`BOOL`	`BooleanType`
`DATE`	`DateType`
`DATETIME`	`TimestampNTZType`, kecuali `StringType` dalam Databricks Runtime 16.4 hingga 17.x**
`TIME`, `TIMESTAMP`	`TimestampType`/`TimestampNTZType`
Jenis apa pun dengan `REPEATED` mode	`ArrayType` dari jenis Spark yang sesuai***

* BigQuery BIGNUMERIC memiliki presisi hingga 76 digit, yang melebihi presisi maksimum DecimalType Spark 38. Secara bawaan, BIGNUMERIC dipetakan ke DecimalType(38, 38). Untuk mengonfigurasi skala, gunakan bigNumericDefaultScale opsi katalog. Nilai yang diizinkan adalah [0, 38]. Misalnya, bigNumericDefaultScale = '10' memetakan BIGNUMERIC ke DecimalType(38, 10). BigQuery NUMERIC menghubungkan ke presisi dan skala yang telah dinyatakan.

** Konektor mulai menggunakan BIGQuery Storage API di Databricks Runtime 16.4. Dari Databricks Runtime 16.4 hingga 17.x, Storage API memetakan BigQuery DATETIME ke Spark StringType alih-alih TimestampNTZType. Databricks Runtime 18.0 memulihkan pemetaan TimestampNTZType.

Di BigQuery, kolom dengan mode REPEATED dipetakan ke Spark ArrayType yang berisi tipe Spark yang sesuai. Misalnya, kolom BigQuery REPEATED STRING memetakan ke ArrayType(VarcharType), dan kolom BigQuery REPEATED INT64 memetakan ke ArrayType(LongType).

Saat Anda membaca dari BigQuery, BigQuery Timestamp dipetakan ke Spark TimestampType jika preferTimestampNTZ = false (default). BigQuery Timestamp dipetakan ke TimestampNTZType jika preferTimestampNTZ = true.

Troubleshooting

Bagian berikut menjelaskan kesalahan umum dan resolusinya saat menggunakan konektor BigQuery.

`Error creating destination table using the following query [<query>]`

Penyebab umum: Akun layanan yang digunakan oleh koneksi tidak memiliki peran Pengguna BigQuery .

Resolusi:

Berikan peran Pengguna BigQuery ke akun layanan yang digunakan oleh koneksi. Peran ini diperlukan untuk membuat himpunan data materialisasi yang menyimpan hasil kueri untuk sementara waktu.
Jalankan kembali kueri.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-08-17

Menjalankan kueri federasi di Google BigQuery

Sebelum Anda mulai

Buat sambungan

Penjelajah Katalog

SQL

Membuat katalog asing

Penjelajah Katalog

SQL

Materialisasi

Membaca tabel eksternal BigQuery

Tabel eksternal yang didukung

Pushdown yang didukung

Pemetaan jenis data

Troubleshooting

Error creating destination table using the following query [<query>]

Saran dan Komentar

Sumber Daya Tambahan:

`Error creating destination table using the following query [<query>]`