Menyinkronkan data BigQuery ke AlloyDB

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Untuk mengetahui informasi tentang akses ke rilis ini, lihat halaman permintaan akses.

Catatan: Fitur sinkronkan data hanya didukung untuk PostgreSQL versi 18.

Halaman ini menunjukkan cara menyinkronkan tabel dari BigQuery ke instance AlloyDB untuk PostgreSQL Anda.

Dengan menyinkronkan data analitik dari BigQuery ke AlloyDB, Anda dapat membangun sistem operasional yang diuntungkan dari akses transaksional latensi rendah ke data lake Anda. Tidak seperti pembungkus data asing (FDW) yang mengkueri data di tempat, tabel sinkronisasi memindahkan data ke penyimpanan AlloyDB untuk performa maksimum.

AlloyDB menyediakan cara berikut untuk memindahkan data BigQuery ke instance Anda:

• Sinkronisasi satu kali: membuat salinan tabel BigQuery Anda yang dapat ditulis dan independen.

• Sinkronisasi berkala (pencerminan): membuat tabel lokal hanya baca yang diperbarui secara otomatis sesuai jadwal—misalnya, setiap 6 jam atau setiap hari.

Pertimbangan performa dan operasional

Saat Anda menggunakan tabel sinkronisasi BigQuery, pertimbangkan hal berikut:

• Penggunaan resource: pergerakan data menggunakan CPU dan memori. Untuk tabel yang sangat besar, pertimbangkan untuk menjadwalkan sinkronisasi di luar jam sibuk agar tidak memengaruhi workload transaksional utama Anda.
• Visibilitas data: selama operasi penggantian, tabel target yang ada akan dihapus dan dibuat ulang di awal. Kueri selama impor awalnya akan melihat tabel kosong, diikuti dengan data yang baru diimpor yang muncul secara bertahap saat transaksi batch dilakukan.

Sebelum memulai

1. Pahami cara bigquery_fdw menangani pemetaan kolom dan jenis data BigQuery, karena ekstensi alloydb_sync menggunakan bigquery_fdw untuk terhubung ke BigQuery.
Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

2. Aktifkan Cloud API yang diperlukan untuk membuat dan menghubungkan ke AlloyDB.

   Aktifkan API

3. Untuk mengonfirmasi nama project yang akan Anda ubah, pada langkah Konfirmasi project, klik Berikutnya.

4. Pada langkah Enable APIs, klik Enable untuk mengaktifkan berikut ini:

   • AlloyDB API
   • Compute Engine API
   • Cloud Resource Manager API
   • Service Networking API
   • BigQuery Storage API

   Service Networking API diperlukan jika Anda berencana mengonfigurasi konektivitas jaringan ke AlloyDB menggunakan jaringan VPC yang berada di project yang sama Google Cloud dengan AlloyDB.

   Compute Engine API dan Cloud Resource Manager API diperlukan jika Anda berencana mengonfigurasi konektivitas jaringan ke AlloyDB menggunakan jaringan VPC yang berada di project Google Cloud lain.

5. Pastikan Anda memiliki tabel BigQuery yang ada untuk menyinkronkan data. Untuk mengetahui informasi selengkapnya, lihat Membuat dan menggunakan tabel BigQuery.

Peran yang diperlukan

Untuk memberikan akses set data BigQuery ke akun layanan cluster AlloyDB, Anda memerlukan izin berikut:

• BigQuery Data Viewer (roles/bigquery.dataViewer) atau peran kustom apa pun dengan izin bigquery.tables.get dan bigquery.tables.getData. Jika diberikan pada akun layanan, peran ini memberikan izin untuk membaca data dan metadata dari tabel atau tampilan.
• BigQuery Read Session User (roles/bigquery.readSessionUser) atau peran kustom apa pun dengan izin bigquery.readsessions.create dan bigquery.readsessions.getData. Memberikan kemampuan untuk membuat dan menggunakan sesi baca.
• Pengguna Tugas BigQuery (roles/bigquery.jobUser) atau peran kustom apa pun dengan izin bigquery.jobs.create. Memberikan kemampuan untuk membuat dan menjalankan tugas, termasuk tugas kueri.

Mengonfigurasi ekstensi

Sebelum menyinkronkan tabel dari BigQuery, aktifkan ekstensi yang diperlukan dan konfigurasi koneksi ke BigQuery.

1. Buat ekstensi.

   1. Hubungkan ke instance AlloyDB menggunakan klien psql dengan mengikuti petunjuk di Menghubungkan klien psql ke instance.

   2. Jalankan perintah berikut:

      CREATE EXTENSION IF NOT EXISTS alloydb_sync;
      

      Catatan: Anda harus membuat ekstensi ini di setiap database tempat Anda ingin menyinkronkan data BigQuery.

2. Untuk mengizinkan AlloyDB melakukan autentikasi dengan BigQuery, buat pemetaan pengguna.

   CREATE EXTENSION IF NOT EXISTS bigquery_fdw;
   CREATE SERVER IF NOT EXISTS BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
   CREATE USER MAPPING IF NOT EXISTS FOR USER SERVER BIGQUERY_SERVER_NAME;
   

   Ganti kode berikut:

   • USER: nama pengguna database atau pengguna IAM yang mengakses tabel BigQuery.
   • BIGQUERY_SERVER_NAME: ID unik untuk server BigQuery. Tentukan ini sekali dalam database tertentu. Anda dapat mengganti BIGQUERY_SERVER_NAME dengan nama server Anda.

Menyinkronkan tabel BigQuery untuk ekspor satu kali

Anda dapat menyinkronkan tabel BigQuery untuk ekspor satu kali menggunakan psql.

Menyinkronkan tabel BigQuery satu kali menggunakan psql

Catatan: Fungsi alloydb_sync.import_bq_table() membuat tabel AlloyDB yang dapat ditulis dan tidak memperbarui data dari BigQuery secara otomatis.

Untuk membuat salinan data BigQuery yang dapat diedit, gunakan psql untuk menjalankan fungsi alloydb_sync.import_bq_table.

SELECT alloydb_sync.import_bq_table(
  'PROJECT_ID.DATASET_ID.TABLE_ID',
  'ALLOYDB_DESTINATION_TABLE_NAME',
  'ON_EXISTS',
  ARRAY['PRIMARY_KEY_COLUMN']
);

Ganti kode berikut:

• PROJECT_ID: ID project tempat set data BigQuery berada.
• DATASET_ID: nama set data BigQuery untuk tabel. Untuk tabel Iceberg dengan nama 4 bagian, ini adalah Catalog.Namespace.
• TABLE_ID: nama tabel atau tampilan BigQuery.
• ALLOYDB_DESTINATION_TABLE_NAME: nama tabel lokal dalam database AlloyDB yang akan dibuat dan diimpor datanya. Anda dapat menyertakan nama skema—misalnya, public.local_sales.
• ON_EXISTS: strategi yang akan digunakan jika tabel tujuan sudah ada.
• PRIMARY_KEY_COLUMN: daftar nama kolom opsional untuk digunakan sebagai kunci utama.

Contoh

Contoh berikut menunjukkan cara menyinkronkan tabel bernama transactions dari set data BigQuery ke tabel AlloyDB baru bernama public.local_sales:

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    'replace'
);

Parameter on_exists

Parameter on_exists menentukan cara fungsi menangani sinkronisasi jika tabel tujuan sudah ada di AlloyDB:

• error: opsi default. Menghentikan sinkronisasi jika tabel tujuan sudah ada.
• skip: melewati sinkronisasi jika tabel tujuan sudah ada.
• replace: menggantikan tabel lokal yang ada dengan data baru dari BigQuery.

Dukungan kunci utama

Jika Anda memberikan parameter primary_key opsional sebagai array teks, AlloyDB akan membuat tabel dengan kolom yang ditentukan sebagai kunci primer.

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    ARRAY['transaction_id']
);

Menyinkronkan tabel BigQuery untuk ekspor berkala

Anda dapat menyinkronkan tabel BigQuery untuk ekspor berkala menggunakan psql.

Membuat sinkronisasi berkala

Untuk mempertahankan tabel hanya baca yang tetap disinkronkan dengan data BigQuery, gunakan psql untuk menjalankan fungsi alloydb_sync.create_bq_sync_table.

SELECT alloydb_sync.create_bq_sync_table(
    'PROJECT_ID.DATASET_ID.TABLE_ID',
    'ALLOYDB_DESTINATION_TABLE_NAME',
    'REFRESH_INTERVAL',
    'ON_EXISTS',
    ARRAY['PRIMARY_KEY_COLUMN']
);

Ganti kode berikut:

• PROJECT_ID.DATASET_ID.TABLE_ID: Nama yang sepenuhnya memenuhi syarat dari tabel atau tampilan BigQuery, termasuk project ID, dataset ID, dan table ID, yang dipisahkan dengan titik. Untuk tabel Iceberg dengan nama 4 bagian, DATASET_ID direpresentasikan sebagai Catalog.Namespace. Contoh, my-gcp-project.sales_data.transactions.
• ALLOYDB_DESTINATION_TABLE_NAME: nama tabel lokal di database AlloyDB untuk membuat dan menyinkronkan data.
• REFRESH_INTERVAL: interval saat AlloyDB memuat ulang data secara berkala dari BigQuery—misalnya, 12 hours.
• ON_EXISTS: strategi yang akan digunakan jika tabel tujuan sudah ada.
• PRIMARY_KEY_COLUMN: daftar nama kolom opsional yang akan digunakan sebagai kunci utama.

Contoh

Contoh berikut menunjukkan cara membuat cerminan profil pelanggan yang diperbarui setiap 12 jam:

SELECT alloydb_sync.create_bq_sync_table(
    'my-gcp-project.crm_data.profiles',
    'public.customer_mirror',
    '12 hours',
    'replace'
);

Memantau dan mengelola tugas

Setelah memulai sinkronisasi, Anda dapat memantau progresnya dan mengelola tugas.

Memeriksa status tugas

Sinkronisasi besar dapat memerlukan waktu. Anda dapat memantau progres, termasuk data yang diproses dan perkiraan waktu penyelesaian, dengan membuat kueri tampilan job_status:

Catatan: Fungsi alloydb_sync.import_bq_table() menampilkan UUID tugas yang dapat Anda cocokkan dengan import_id di tampilan alloydb_sync.job_status.

SELECT
    import_id,
    status,
    records_processed,
    total_records,
    error
FROM alloydb_sync.job_status;

Misalnya, untuk membatalkan tugas, jalankan perintah berikut:

SELECT alloydb_sync.cancel_import_job('85bb5dfa-dfb9-4017-9153-738f55abe4b1');

Menghentikan dan menghapus tugas sinkronisasi

Untuk berhenti mencerminkan tabel BigQuery dan menghapus tabel lokal, gunakan fungsi alloydb_sync.delete_bq_sync_table:

SELECT alloydb_sync.delete_bq_sync_table('public.customer_mirror');

Penting: Anda harus menggunakan fungsi ini, bukan perintah DROP TABLE PostgreSQL standar untuk menghapus tabel yang direplikasi. Menghapus tabel sinkronisasi secara manual tanpa fungsi ini tidak akan menghapus hook penjadwal latar belakang, yang dapat menyebabkan penjadwal terus mengalami error dan menguras slot pekerja latar belakang.

Batasan

Batasan berikut berlaku saat menyinkronkan tabel dari BigQuery:

• Fitur ini hanya didukung untuk PostgreSQL versi 18.
• Jika Anda DROP ekstensi alloydb_sync, Anda harus memulai ulang instance sebelum membuat ekstensi lagi.
• Sinkronisasi berjalan dalam transaksi. Jika tugas impor terganggu atau gagal, sistem akan melakukan roll back data yang diimpor.
• Jika dua pengguna memulai tugas sinkronisasi secara bersamaan dengan tabel target yang sama, tabel tersebut dapat saling menimpa.
• Jika terjadi gangguan selama impor latar belakang awal untuk tabel sinkronisasi yang baru terdaftar, tabel akan tetap tidak lengkap hingga interval refresh terjadwal berikutnya. Untuk mengatasinya, Anda dapat menghapus tabel sinkronisasi menggunakan fungsi alloydb_sync.delete_bq_sync_table() dan membuatnya ulang.
• Jenis BigQuery yang kompleks seperti ARRAY, BYTES, VECTOR, dan GEOGRAPHY tidak didukung untuk sinkronisasi. Untuk mengetahui daftar lengkapnya, lihat Jenis data dan pemetaan kolom BigQuery yang didukung.
• Jangan menghapus tabel yang direplikasi secara manual. Gunakan fungsi API alloydb_sync.delete_bq_sync_table() untuk menghapus tabel secara aman dan melakukan refresh.
• Untuk menghapus database yang menggunakan ekstensi alloydb_sync, Anda harus menggunakan DROP DATABASE ... WITH (FORCE).
• Jika database Postgres mengalami error saat impor sedang berjalan, metadata mungkin akan macet dalam status RUNNING, sehingga memblokir impor di masa mendatang. Anda harus menjalankan UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING'; secara manual untuk berhenti memblokirnya.

Harga

Saat menyinkronkan data dari BigQuery ke AlloyDB, Anda akan ditagih menggunakan harga komputasi kapasitas BigQuery.

Setelah data diekspor, Anda dikenai biaya penyimpanan data di AlloyDB. Untuk mengetahui informasi selengkapnya, lihat Harga AlloyDB untuk PostgreSQL.

Langkah berikutnya

• Pelajari lebih lanjut Mengekspor data ke AlloyDB (ETL terbalik).
• Pelajari lebih lanjut cara membuat kueri data BigQuery di tempat menggunakan FDW.