Menyinkronkan data BigQuery ke AlloyDB

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.
  2. 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.

  3. 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.

    Go to project selector

  4. Verify that billing is enabled for your Google Cloud project.

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

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

    Aktifkan API

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

  9. 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.

  10. 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. Jika Anda menggunakan konsol Google Cloud , AlloyDB akan melakukan langkah-langkah ini secara otomatis.

  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;

  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 Google Cloud konsol atau dengan menggunakan psql.

Menggunakan Google Cloud console

Untuk menyinkronkan tabel BigQuery ke AlloyDB menggunakan Google Cloud konsol, lakukan hal berikut:

  1. Buka halaman BigQuery di konsol Google Cloud .

    Buka halaman BigQuery

  2. Di panel kiri, klik Explorer:

    Jika Anda tidak melihat panel kiri, klik Luaskan panel kiri untuk membuka panel.

  3. Di panel Explorer, luaskan project Anda, klik Set Data, lalu klik set data Anda.

  4. Klik Ringkasan > Tabel, lalu pilih tabel.

  5. Di panel detail, klik upload Ekspor / sinkronkan > AlloyDB (Ekspor sekali atau sinkronkan).

  6. Di bagian Pilih cluster target, pilih salah satu opsi berikut:

    • Pilih Gunakan cluster yang ada untuk mengekspor tabel BigQuery ke cluster AlloyDB yang ada. Kemudian, lakukan hal berikut:

      1. Pilih cluster AlloyDB utama.

      2. Pilih database AlloyDB tujuan.

      3. Pilih skema untuk tabel AlloyDB tujuan Anda.

      4. Tentukan nama untuk tabel AlloyDB tujuan Anda.

      5. Untuk Sync frequency, pilih Just once untuk membuat salinan tabel BigQuery.

      6. Klik Siapkan ekspor.

      Setelah penyiapan sinkronisasi selesai, Anda dapat menggunakan pernyataan SQL yang diberikan untuk melacak tugas impor dan mengkueri tabel yang diimpor. Klik Query untuk diarahkan ke tabel yang diimpor di AlloyDB Studio.

    • Pilih Create a new cluster untuk mengekspor tabel BigQuery ke cluster AlloyDB baru. Kemudian, lakukan hal berikut:

      1. Klik Siapkan ekspor.

      2. Pada dialog Redirect to AlloyDB, pilih Redirect.

      3. Pilih jenis cluster, baik Cluster uji coba gratis atau Cluster yang disediakan.

      4. Klik Lanjutkan.

      5. Di Konfigurasi Sinkronisasi, pilih database AlloyDB tujuan postgres default, skema public default untuk tabel AlloyDB tujuan, dan tentukan nama untuk tabel AlloyDB tujuan.

        Untuk Sync frequency, pilih Just once untuk membuat salinan tabel BigQuery.

      6. Klik Lanjutkan.

      7. Konfigurasikan cluster Anda. Untuk mengetahui informasi selengkapnya tentang setiap kolom, lihat Membuat cluster dan instance utama baru.

      8. Klik Create cluster.

      Setelah penyiapan sinkronisasi selesai, buka AlloyDB Studio untuk mengkueri tabel yang diimpor.

Menyinkronkan tabel BigQuery satu kali menggunakan psql

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 konsolGoogle Cloud atau dengan menggunakan psql.

Menggunakan Google Cloud console

Untuk menyinkronkan tabel BigQuery ke AlloyDB menggunakan Google Cloud konsol, lakukan hal berikut:

  1. Buka halaman BigQuery di konsol Google Cloud .

    Buka halaman BigQuery

  2. Di panel kiri, klik Explorer:

    Tombol yang ditandai untuk panel Explorer.

    Jika Anda tidak melihat panel kiri, klik Luaskan panel kiri untuk membuka panel.

  3. Di panel Explorer, luaskan project Anda, klik Set Data, lalu klik set data Anda.

  4. Klik Ringkasan > Tabel, lalu pilih tabel.

  5. Di panel detail, klik upload Ekspor / sinkronkan > AlloyDB (Ekspor sekali atau sinkronkan).

  6. Di bagian Pilih cluster target, pilih salah satu opsi berikut:

    • Pilih Gunakan cluster yang ada untuk mengekspor tabel BigQuery ke cluster AlloyDB yang ada. Kemudian, lakukan hal berikut:

      1. Pilih cluster AlloyDB utama.

      2. Pilih database AlloyDB tujuan.

      3. Pilih skema untuk tabel AlloyDB tujuan Anda.

      4. Tentukan nama untuk tabel AlloyDB tujuan Anda.

      5. Untuk Frekuensi sinkronisasi, pilih jangka waktu untuk membuat sinkronisasi berkala tabel BigQuery.—misalnya, Setiap jam, Setiap enam jam.

      6. Klik Siapkan ekspor.

      Setelah penyiapan sinkronisasi selesai, Anda dapat menggunakan pernyataan SQL yang diberikan untuk melacak tugas impor dan membuat kueri tabel yang diimpor. Klik Query untuk diarahkan ke tabel yang diimpor di AlloyDB Studio.

    • Pilih Create a new cluster untuk mengekspor tabel BigQuery ke cluster AlloyDB baru. Kemudian, lakukan hal berikut:

      1. Klik Siapkan ekspor.

      2. Pada dialog Redirect to AlloyDB, pilih Redirect.

      3. Pilih jenis cluster, baik Cluster uji coba gratis atau Cluster yang disediakan.

      4. Klik Lanjutkan.

      5. Di Konfigurasi Sinkronisasi, pilih database AlloyDB tujuan postgres default, skema public default untuk tabel AlloyDB tujuan, dan tentukan nama untuk tabel AlloyDB tujuan.

        Untuk Sync frequency, pilih Just once untuk membuat salinan tabel BigQuery.

      6. Klik Lanjutkan.

      7. Konfigurasikan cluster Anda. Untuk mengetahui informasi selengkapnya tentang setiap kolom, lihat Membuat cluster dan instance utama baru.

      8. Klik Create cluster.

      Setelah penyiapan sinkronisasi selesai, buka AlloyDB Studio untuk mengkueri tabel yang diimpor.

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:

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');

Pemetaan jenis data

Saat Anda menyinkronkan atau mengimpor data dari BigQuery ke AlloyDB menggunakan ekstensi alloydb_sync, AlloyDB memetakan jenis data BigQuery ke jenis data PostgreSQL yang sesuai dalam tabel target Anda.

Pastikan kolom tabel BigQuery sumber Anda menggunakan jenis data yang didukung berikut.

Tabel berikut mencantumkan pemetaan jenis data antara BigQuery dan AlloyDB.

Jenis data tabel BigQuery Jenis data tabel asing PostgreSQL yang direkomendasikan

BOOLEAN

BOOLEAN

INTEGER (INT64)

BIGINT

FLOAT (FLOAT64)

DOUBLE PRECISION

STRING

VARCHAR

NUMERIC

NUMERIC(38, 9)

NUMERIC(P[, S])

NUMERIC(P, S)

BIGNUMERIC

NUMERIC(77, 38)

BIGNUMERIC(P[, S])

NUMERIC(P, S)

DATE

DATE

TIMESTAMP

TIMESTAMPTZ

TIME

TIME

JSON

JSONB

BYTES

BYTEA

GEOGRAPHY

GEOGRAPHY(POINT), ...

Untuk mengetahui informasi selengkapnya, lihat PostGIS_Geography.

DATETIME

TIMESTAMP

ARRAY

VECTOR(N)

N adalah dimensi vektor. Anda harus menetapkan tanda bigquery_fdw.enable_vector_downcasting dalam sesi. Karena jenis VECTOR di AlloyDB menggunakan jenis float4, Anda mungkin mengalami kehilangan presisi dalam konversi ini.

Untuk mengetahui informasi selengkapnya, lihat ekstensi pgvector.

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 BigQuery dan pemetaan kolom 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 pembacaan streaming BigQuery (Storage Read API).

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

Langkah berikutnya