Mengakses data Iceberg dari AlloyDB

Pratinjau — Akses Iceberg langsung

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.

Akses Iceberg langsung di AlloyDB untuk PostgreSQL memungkinkan Anda mengkueri data yang disimpan dalam format tabel Apache Iceberg di Cloud Storage dari instance AlloyDB. Anda dapat mengakses set data Iceberg menggunakan URI bucket Cloud Storage atau menggunakan katalog runtime Lakehouse. Untuk mempercepat workload analisis, AlloyDB menyediakan columnar engine bawaan yang mengoptimalkan pemindaian, penggabungan, dan agregasi. Dengan berintegrasi dengan columnar engine, akses Iceberg langsung memungkinkan Anda menjalankan kueri analisis berperforma tinggi di data lakehouse tanpa membangun, mengelola, atau memelihara pipeline data ekstrak, transformasi, dan pemuatan (ETL) yang kompleks.

Anda dapat mengkueri tabel Iceberg menggunakan perintah SQL standar, menggabungkan set data Iceberg dengan tabel operasional di AlloyDB, dan mengisi tabel Iceberg ke dalam columnar engine dalam memori untuk mempercepat performa kueri.

Manfaat

Akses Iceberg langsung memberikan manfaat berikut:

• Akses lakehouse tanpa ETL: buat kueri set data Iceberg eksternal di tempat tanpa menyalin atau memindahkan data ke sistem analisis terpisah.
• Kueri transaksional dan analisis terpadu: gabungkan data operasional langsung yang disimpan dalam tabel heap AlloyDB dengan data historis dalam jumlah besar yang disimpan dalam tabel Iceberg di Cloud Storage.
• Integrasi katalog yang fleksibel: akses metadata tabel Iceberg dari jalur bucket Cloud Storage atau melalui katalog runtime Lakehouse.
• Percepatan kueri berbentuk kolom: menyimpan dalam cache dan mengisi tabel Iceberg ke dalam memori columnar engine AlloyDB untuk pemrosesan analisis sub-detik.
• Antarmuka SQL standar: gunakan sintaksis PostgreSQL yang sudah dikenal untuk membuat kueri dan menganalisis tabel Iceberg.

Cara kerja akses Iceberg langsung

Akses Iceberg langsung menggunakan antarmuka Metode Akses Tabel (TAM) PostgreSQL (USING iceberg) dan terintegrasi dengan perencana dan framework eksekusi columnar engine AlloyDB.

Saat Anda mengkueri tabel Iceberg, AlloyDB beroperasi dalam salah satu mode berikut:

• Pemindaian langsung (untuk pembacaan streaming): AlloyDB membaca metadata dan file data terbaru langsung dari Cloud Storage. Mesin berbentuk kolom memproses data secara streaming.
• Akselerasi columnar engine (untuk pembacaan yang di-cache dalam memori): saat Anda mengisi tabel Iceberg ke dalam columnar engine AlloyDB menggunakan fungsi google_columnar_engine_add(), tabel akan dimuat ke dalam penyimpanan kolom dalam memori. Kueri berikutnya membaca dari memori mesin berbasis kolom, sehingga memaksimalkan throughput kueri dan meminimalkan latensi.

Penyajian snapshot dan pembaruan cache

Snapshot tabel Iceberg yang dikueri AlloyDB bergantung pada mode baca:

• Pemindaian langsung: AlloyDB menjalankan kueri pada snapshot Iceberg terbaru. Saat kueri dimulai, AlloyDB menentukan snapshot tabel Iceberg terbaru yang tersedia dan membaca data dari snapshot tersebut, bahkan dalam transaksi REPEATABLE READ atau SERIALIZABLE. AlloyDB tidak mendukung penyematan snapshot dan kueri point-in-time di seluruh transaksi.

  Misalnya, saat Anda mengkueri tabel menggunakan pemindaian langsung, setiap pernyataan dalam transaksi akan membaca dari snapshot terbaru yang tersedia:

  BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
  SELECT * FROM customer_orders;
  -- If an external process commits a new Iceberg snapshot:
  SELECT * FROM customer_orders; -- Returns results from the new snapshot.
  COMMIT;
  

• Akselerasi columnar engine: AlloyDB menjalankan kueri pada snapshot yang diisi di columnar engine. Jika AlloyDB menulis data baru ke tabel Iceberg yang mendasarinya di Cloud Storage setelah pengisian, tabel Iceberg yang mendasarinya di Cloud Storage setelah pengisian, kueri mungkin menampilkan data yang tidak berlaku. Untuk mendapatkan data terbaru setelah operasi DML pada tabel pokok, muat ulang cache menggunakan fungsi google_columnar_engine_refresh().

Jenis data yang didukung

Saat Anda menentukan tabel Iceberg di AlloyDB, nama kolom dan jenis data dalam pernyataan DDL Anda harus cocok dengan jenis dalam skema Iceberg yang mendasarinya.

Akses Iceberg langsung mendukung jenis data Apache Iceberg berikut dan jenis AlloyDB yang sesuai:

Jenis data Apache Iceberg	Jenis data AlloyDB	Deskripsi
boolean	BOOLEAN	Konversi yang di-vektorisasi ke format byte-packed
int	INT/INTEGER	Bilangan bulat 32-bit bertanda
long	BIGINT	Bilangan bulat 64-bit yang telah ditandai.
float	REAL/FLOAT4	Floating point presisi tunggal 32-bit
double	DOUBLE PRECISION/FLOAT8	Floating point presisi ganda 64-bit
decimal(P, S)	NUMERIC(P, S)/DECIMAL(P, S)	Nilai numerik fixed-point dengan presisi P dan skala S
string	TEXT/VARCHAR	Nilai string UTF-8
date	DATE	Tanggal kalender (tahun, bulan, hari)
timestamp	TIMESTAMP	Stempel waktu tanpa zona waktu
timestamptz	TIMESTAMPTZ	Stempel waktu dengan zona waktu

Batasan

Akses Iceberg langsung memiliki batasan berikut:

• Ketersediaan versi PostgreSQL: AlloyDB mendukung akses Iceberg langsung di PostgreSQL 18 dan yang lebih baru.
• Izin pengguna: hanya pengguna database dengan peran alloydbsuperuser yang dapat membuat tabel Iceberg. Setelah tabel dibuat, Anda dapat memberikan izin SELECT kepada pengguna lain untuk membuat kueri tabel Iceberg.
• Operasi hanya baca: AlloyDB hanya mendukung kueri SELECT (DQL) pada tabel Iceberg. Alat ini tidak mendukung operasi tulis (INSERT, UPDATE, DELETE, TRUNCATE).
• Versi spesifikasi Apache Iceberg: AlloyDB tidak mendukung file penghapusan Iceberg v2 (penghapusan posisi dan kesetaraan) atau vektor penghapusan Iceberg v3.
• Dukungan format file: akses Iceberg langsung mendukung file data Parquet, serta file metadata JSON dan Avro. Alat ini tidak mendukung file data ORC.
• Pembuatan versi snapshot: kueri pemindaian langsung berjalan pada snapshot tabel Iceberg terbaru, dan kueri yang dipercepat berbasis kolom berjalan pada snapshot yang diisi. AlloyDB tidak mendukung kueri point-in-time.
• Evolusi skema: AlloyDB tidak mendukung operasi ALTER TABLE pada tabel Iceberg. Tabel Iceberg yang mendasarinya tidak boleh mengalami migrasi skema.
• Dukungan katalog metadata: akses Iceberg langsung mendukung jalur bucket Cloud Storage langsung (gs://) dan jalur katalog runtime Lakehouse (bl://). Untuk katalog runtime Lakehouse, AlloyDB hanya mendukung mode kredensial pengguna akhir. Katalog ini tidak mendukung mode penjualan kredensial atau katalog REST lainnya.
• Bucket Pemohon Membayar: AlloyDB tidak mendukung bucket Cloud Storage yang menggunakan Pemohon Membayar.
• Batasan populasi penuh: AlloyDB tidak mendukung populasi kolom parsial untuk tabel Iceberg. Tabel harus sesuai dengan memori mesin berbentuk kolom atau ruang SSD.
• Memori heap populasi: mengisi tabel Iceberg yang berisi grup baris Parquet besar dapat melebihi batas memori heap populasi per worker, terutama pada instance dengan vCPU yang lebih sedikit. Untuk mengatasi masalah ini, lihat Heap populasi columnar engine penuh.

Sebelum memulai

Sebelum membuat dan mengkueri tabel Iceberg, pastikan Anda menyelesaikan hal berikut:

1. Buat cluster AlloyDB yang menjalankan PostgreSQL 18 atau yang lebih baru di Google Cloud. Untuk mengetahui informasi selengkapnya, lihat Membuat cluster.
2. Menghosting tabel Apache Iceberg di Cloud Storage atau yang terdaftar di katalog runtime Lakehouse:
   • Untuk jalur Cloud Storage, struktur direktori bucket harus mengikuti tata letak Apache Iceberg standar yang berisi subdirektori data/ dan metadata/, termasuk file JSON metadata dan version-hint.text. Untuk mengetahui informasi selengkapnya, lihat Membuat bucket.
   • Untuk katalog runtime Lakehouse, buat dan daftarkan katalog Iceberg Anda dalam mode kredensial pengguna akhir. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan endpoint katalog REST Apache Iceberg.
3. Siapkan kredensial database untuk pengguna dengan peran alloydbsuperuser. Untuk mengetahui informasi selengkapnya, lihat peran grup alloydbsuperuser.

Peran yang diperlukan

Agar AlloyDB dapat membaca data dan metadata Iceberg, Anda harus memberikan peran IAM yang diperlukan ke akun layanan cluster AlloyDB:

• Akses Cloud Storage: berikan peran Storage Object Viewer (roles/storage.objectViewer) pada bucket Cloud Storage yang berisi data dan metadata Iceberg Anda.
• Akses BigLake (jika menggunakan katalog runtime Lakehouse): berikan peran BigLake Viewer (roles/biglake.viewer) pada project yang menghosting katalog BigLake Anda.

Untuk menemukan akun layanan cluster, jalankan perintah gcloud beta alloydb clusters describe:

gcloud beta alloydb clusters describe CLUSTER_ID --region=REGION_ID

Ganti kode berikut:

• CLUSTER_ID: ID cluster AlloyDB.
• REGION_ID: lokasi cluster AlloyDB. Contoh, us-east1. Untuk mengetahui daftar lengkap region, lihat Lokasi AlloyDB.

Output-nya berisi kolom serviceAccountEmail, yang merupakan akun layanan untuk cluster ini. Di konsol Google Cloud , Anda dapat menemukan akun layanan di halaman Ringkasan cluster.

Untuk memberikan peran Storage Object Viewer menggunakan gcloud CLI, jalankan:

gcloud storage buckets add-iam-policy-binding \
    gs://BUCKET_NAME \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectViewer"

Jika Anda menggunakan katalog runtime Lakehouse, berikan peran BigLake Viewer:

gcloud projects add-iam-policy-binding LAKEHOUSE_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/biglake.viewer"

Ganti kode berikut:

• BUCKET_NAME: nama bucket Cloud Storage Anda.
• LAKEHOUSE_PROJECT_ID: project ID Google Cloud tempat katalog runtime Lakehouse Anda dihosting.
• SERVICE_ACCOUNT_EMAIL: email akun layanan cluster yang Anda temukan di kolom serviceAccountEmail.

Mengonfigurasi flag database

Untuk mengaktifkan columnar engine dan akses Iceberg langsung, Anda dapat mengonfigurasi flag database di instance AlloyDB. Tetapkan flag database berikut pada instance Anda:

Flag database	Nilai	Deskripsi
google_columnar_engine.enabled	on	Mengaktifkan columnar engine AlloyDB.
google_columnar_engine.enable_iceberg_reads	on	Mengaktifkan akses Iceberg langsung. Memerlukan mulai ulang instance.
google_columnar_engine.memory_size_in_mb	SIZE_IN_MB	(Opsional) Mengalokasikan memori ke columnar engine. Direkomendasikan jika Anda berencana mengisi tabel Iceberg dalam memori.

Untuk mengonfigurasi flag ini menggunakan gcloud CLI, jalankan perintah gcloud alloydb instances update:

gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_iceberg_reads=on

Ganti kode berikut:

• INSTANCE_ID: ID instance AlloyDB Anda.
• CLUSTER_ID: ID cluster AlloyDB Anda.
• REGION_ID: ID wilayah cluster AlloyDB Anda.

Membuat tabel Iceberg di AlloyDB

Untuk mengekspos set data Apache Iceberg di AlloyDB, hubungkan sebagai pengguna dengan hak istimewa alloydbsuperuser. Kemudian, buat tabel menggunakan metode akses tabel USING iceberg.

CREATE TABLE TABLE_NAME (
    COLUMN_NAME DATA_TYPE [, ...]
)
USING iceberg
WITH (
    uri = 'LOCATION_URI'
);

Ganti kode berikut:

• TABLE_NAME: nama tabel yang akan dibuat di AlloyDB.
• COLUMN_NAME dan DATA_TYPE: definisi kolom. Nama dan jenis kolom harus cocok dengan skema tabel Iceberg yang mendasarinya.
• LOCATION_URI: lokasi metadata tabel Iceberg. Tentukan salah satu format berikut:
  • Jalur Cloud Storage langsung: gs://BUCKET_NAME/PATH_TO_ICEBERG_TABLE
  • URI katalog runtime Lakehouse: bl://projects/PROJECT_ID/catalogs/CATALOG_NAME/databases/DATABASE_NAME/tables/TABLE_NAME

Contoh

Contoh berikut menunjukkan cara membuat tabel Iceberg di AlloyDB.

Membuat tabel dari jalur Cloud Storage

Contoh berikut membuat tabel bernama customer_orders yang didukung oleh set data Iceberg yang terletak di bucket Cloud Storage:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'gs://my-iceberg-analytics-bucket/datasets/sales/customer_orders'
);

Membuat tabel dari katalog runtime Lakehouse

Contoh berikut membuat tabel yang merujuk ke tabel Iceberg yang dikelola oleh katalog runtime Lakehouse:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'bl://projects/my-analytics-project/catalogs/sales_catalog/databases/retail_db/tables/customer_orders'
);

Membuat kueri data Iceberg

Setelah membuat tabel di AlloyDB, Anda dapat mengkuerinya menggunakan pernyataan SELECT SQL standar dengan hak istimewa alloydbsuperuser. Secara opsional, Anda dapat memberikan izin baca kepada pengguna tanpa hak istimewa alloydbsuperuser dengan menggunakan pernyataan GRANT. Contoh, GRANT SELECT ON customer_orders TO normal_user.

Data kueri

Contoh berikut menunjukkan cara menjalankan kueri:

SELECT
    customer_id,
    COUNT(order_id) AS total_orders,
    SUM(total_amount) AS total_spent
FROM customer_orders
WHERE is_completed = true
  AND order_date >= '2026-01-01'
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10;

Membuat kueri data Iceberg gabungan dengan data operasional

Anda dapat menggabungkan data operasional real-time yang berada di AlloyDB dengan data historis yang berada di Iceberg:

SELECT
    c.customer_name,
    c.account_tier,
    COUNT(o.order_id) AS total_orders,
    SUM(o.total_amount) AS historical_spend
FROM customer_orders o
JOIN customers c ON o.customer_id = c.customer_id
WHERE o.is_completed = true
GROUP BY c.customer_name, c.account_tier
ORDER BY historical_spend DESC;

Mengimpor data ke tabel lokal

Untuk membuat salinan data Iceberg yang independen dan dapat ditulis di penyimpanan AlloyDB lokal, jalankan CREATE TABLE ... AS SELECT, seperti yang ditunjukkan dalam contoh berikut:

CREATE TABLE local_customer_orders AS
SELECT * FROM customer_orders
WHERE order_date >= '2026-01-01';

Mempercepat kueri menggunakan columnar engine

Untuk workload analisis yang memerlukan latensi ultra-rendah, Anda dapat mengisi tabel Iceberg langsung ke memori columnar engine AlloyDB.

Mengisi tabel Iceberg ke dalam penyimpanan berbentuk kolom

Untuk mengisi semua kolom tabel Iceberg ke dalam columnar engine AlloyDB, gunakan fungsi google_columnar_engine_add(). Contoh:

SELECT google_columnar_engine_add('customer_orders');

Untuk mengisi hanya kolom tertentu yang digunakan kueri Anda, teruskan daftar nama kolom yang dipisahkan koma sebagai argumen kedua. Contoh:

SELECT google_columnar_engine_add('customer_orders', 'customer_id,order_status');

Untuk mengetahui informasi selengkapnya, lihat Menambahkan kolom menggunakan fungsi SQL.

Memuat ulang data yang diisi

Jika Anda menulis snapshot baru ke set data Iceberg yang mendasarinya, muat ulang tabel untuk memuat ulang data terbaru ke dalam columnar engine agar kueri menampilkan hasil terbaru:

SELECT google_columnar_engine_refresh('customer_orders');

Menghapus tabel dari penyimpanan berbentuk kolom

Untuk menghapus tabel Iceberg dari penyimpanan berbasis kolom dan kembali ke pemindaian langsung:

SELECT google_columnar_engine_drop('customer_orders');

Memantau dan memverifikasi eksekusi kueri

Anda dapat memantau cara AlloyDB menjalankan kueri terhadap tabel Iceberg dan memverifikasi apakah kueri menggunakan columnar engine dalam memori. Gunakan tampilan sistem untuk memeriksa status pengisian cache, dan gunakan EXPLAIN untuk memeriksa rencana eksekusi kueri.

Memverifikasi status cache kolom

Untuk memverifikasi apakah tabel Iceberg diisi di columnar engine, buat kueri tampilan sistem g_columnar_relations:

SELECT relation_name, status
FROM g_columnar_relations
WHERE relation_name = 'customer_orders';

Nilai status dari USABLE mengonfirmasi bahwa tabel di-cache dalam memori columnar engine.

Memeriksa rencana eksekusi kueri dengan EXPLAIN

Untuk memverifikasi apakah kueri memanfaatkan columnar engine, gunakan pernyataan EXPLAIN:

EXPLAIN (ANALYZE, COSTS OFF)
SELECT SUM(total_amount)
FROM customer_orders
WHERE is_completed = true;

Output menunjukkan eksekusi berbasis kolom melalui node Custom Scan (ColumnarScan) pada tabel:

Custom Scan (ColumnarScan) on customer_orders
  Filter: (is_completed = true)

Pemecahan masalah

Bagian ini menjelaskan cara menyelesaikan masalah umum saat Anda mengonfigurasi dan membuat kueri tabel Iceberg di AlloyDB.

Flag google_columnar_engine.enable_iceberg_reads dinonaktifkan

Penyebab: Flag database untuk akses Iceberg langsung dinonaktifkan.

Perbaikan yang direkomendasikan: tetapkan flag database google_columnar_engine.enabled=on dan google_columnar_engine.enable_iceberg_reads=on di instance Anda, lalu mulai ulang instance.

Izin ditolak saat mengakses Cloud Storage

Penyebab: Akun layanan cluster AlloyDB tidak memiliki akses baca ke bucket Cloud Storage.

Perbaikan yang direkomendasikan: berikan peran roles/storage.objectViewer ke akun layanan cluster di bucket.

Izin ditolak saat mengakses katalog runtime Lakehouse

Penyebab: Akun layanan cluster AlloyDB tidak memiliki akses baca ke katalog runtime Lakehouse.

Perbaikan yang direkomendasikan: berikan peran roles/biglake.viewer ke akun layanan cluster di project Google Cloud yang menghosting katalog runtime Lakehouse.

Pengisian kolom gagal

Penyebab: Ukuran tabel Iceberg melebihi memori dan ruang SSD yang tersedia di columnar engine.

Perbaikan yang direkomendasikan: tingkatkan alokasi memori ke columnar engine menggunakan flag google_columnar_engine.memory_size_in_mb pada instance Anda, atau tingkatkan ukuran cache penyimpanan columnar engine menggunakan flag google_columnar_engine.storage_cache_size. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi cache penyimpanan untuk columnar engine.

Heap populasi columnar engine penuh

Pesan error:

ERROR: Columnar engine population heap is full during population. Set
google_columnar_engine.population_heap_size_in_mb to a bigger value.

Penyebab: Memori yang diperlukan untuk mengisi grup baris Parquet yang besar melebihi batas heap populasi per worker.

Perbaikan yang direkomendasikan: kurangi jumlah worker populasi paralel agar proses populasi dapat menggunakan heap yang lebih besar. Dalam sesi SQL tempat Anda mengisi tabel, tetapkan flag google_job_scheduler.max_parallel_workers_per_job ke 0 sebelum memanggil fungsi google_columnar_engine_add():

SET google_job_scheduler.max_parallel_workers_per_job = 0;
SELECT google_columnar_engine_add('TABLE_NAME');

Ganti TABLE_NAME dengan nama tabel Iceberg di AlloyDB.

Langkah berikutnya

• Pelajari columnar engine AlloyDB.
• Pelajari cara mengonfigurasi columnar engine.
• Pilih cara mengakses data BigQuery dari AlloyDB.