Ringkasan tampilan Apache Iceberg

Dengan tampilan Apache Iceberg, Anda dapat menentukan tabel logis terbuka yang tidak terwujud dengan SQL dan menggunakannya dari mesin yang kompatibel dengan Iceberg seperti Apache Spark, Trino, Apache Flink, PyIceberg, dan dbt. Anda dapat menggunakan tampilan Iceberg untuk membangun pipeline SQL modular dan mengekspos proyeksi zero-copy yang diseleksi di tabel Iceberg. Tampilan Iceberg dikelola oleh katalog runtime Lakehouse melalui endpoint katalog REST Apache Iceberg, dan tampilan tersebut mengikuti spesifikasi tampilan Apache Iceberg dan spesifikasi OpenAPI REST Iceberg.

Dokumen ini menyebut tampilan ini sebagai tampilan Iceberg.

Tidak seperti tampilan yang diotorisasi BigQuery, tampilan Iceberg dievaluasi di sisi klien oleh compute engine Anda. Tampilan Iceberg adalah objek katalog yang Anda buat, kelola, dan kueri dari mesin open source.

Kemampuan

Kemampuan berikut didukung:

  • Siklus proses tampilan penuh: Membuat, mengganti, mengubah properti, mencantumkan, memeriksa, dan menghapus tampilan Iceberg dari mesin open source yang kompatibel dengan Iceberg seperti Apache Spark dan Trino.
  • Definisi tampilan yang lengkap: Menentukan tampilan dengan alias kolom, komentar tingkat kolom dan tingkat tampilan, properti kustom, join, agregasi, ekspresi tabel umum (CTE), UNION ALL, subkueri, tampilan bertingkat, dan perjalanan waktu pada tabel yang mendasarinya.
  • Autentikasi fleksibel: Gunakan kredensial pengguna akhir atau penjualan kredensial dengan bucket Cloud Storage standar dan bucket namespace hierarkis.
  • Dukungan katalog: Buat tampilan di katalog multi-bucket dan katalog bucket tunggal.

Anda dapat membuat, mengelola, dan mengkueri tampilan Iceberg hanya melalui mesin open source yang kompatibel dengan Iceberg yang terhubung ke endpoint katalog REST Apache Iceberg. Untuk mengetahui informasi selengkapnya, lihat Batasan.

Untuk Spark, gunakan Spark 3.5 atau yang lebih baru dengan runtime Iceberg 1.6.0 atau yang lebih baru. Gunakan runtime Iceberg 1.10.0 atau yang lebih baru agar Spark menemukan endpoint tampilan yang didukung melalui respons GET /v1/config katalog. Tetapkan spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions agar Spark mendelegasikan DDL dan resolusi tampilan ke endpoint katalog REST Apache Iceberg.

Untuk Trino, gunakan Trino 482 atau yang lebih baru. Untuk mengetahui informasi selengkapnya, lihat Dukungan Trino.

Cara kerja tampilan Iceberg

Tampilan Iceberg menyimpan definisi, skema, dan properti SQL-nya dalam file metadata.json berversi di Cloud Storage, di bagian VIEW_LOCATION/metadata/. Katalog runtime Lakehouse melacak lokasi metadata saat ini untuk setiap tampilan dan mengekspos tampilan melalui endpoint tampilan dari endpoint katalog REST Apache Iceberg.

Compute Engine Anda mengevaluasi tampilan Iceberg di sisi klien. Saat Anda menjalankan SELECT * FROM my_view, mesin akan memuat definisi tampilan dari katalog, menyelesaikan setiap tabel yang direferensikan dan tampilan bertingkat, lalu menjalankan kueri terhadap tabel Iceberg yang mendasarinya. Katalog tidak menjalankan kueri atas nama Anda.

Setiap kali Anda mengganti tampilan dengan CREATE OR REPLACE VIEW, katalog akan menulis file metadata.json baru, menambahkan versi dan skema baru ke metadata tampilan, dan mempertahankan view-uuid tampilan. Properti version.history.num-entries membatasi jumlah versi yang dipertahankan. Untuk mengetahui informasi selengkapnya, lihat Melihat properti.

Tabel dan tampilan memiliki namespace ID yang sama dalam namespace katalog. Anda tidak dapat membuat tampilan dengan nama yang sama dengan tabel yang ada, atau mengganti tabel dengan tampilan.

Peran dan izin yang diperlukan

Karena Compute Engine Anda mengevaluasi tampilan di sisi klien, membuat kueri tampilan memerlukan izin pada tampilan dan pada setiap tabel serta tampilan bertingkat yang dirujuk oleh tampilan tersebut.

Untuk mendapatkan izin yang Anda perlukan untuk membuat, mengelola, dan mengkueri tampilan Iceberg, minta administrator untuk memberi Anda peran IAM berikut pada project dan bucket penyimpanan Anda:

  • Membuat, mengganti, mengubah, dan menghapus tampilan: BigLake Editor (roles/biglake.editor) - project Anda
  • Mencantumkan dan memeriksa definisi tampilan: BigLake Viewer (roles/biglake.viewer) - project Anda
  • Tampilan kueri dalam mode penjualan kredensial: BigLake Viewer (roles/biglake.viewer) - project Anda
  • Membuat kueri tampilan dalam mode kredensial pengguna akhir:
    • BigLake Viewer (roles/biglake.viewer) - project Anda
    • Storage Object Viewer (roles/storage.objectViewer) - bucket Cloud Storage
  • Tulis file metadata tampilan dalam mode kredensial pengguna akhir: Storage Object User (roles/storage.objectUser) - bucket Cloud Storage

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk membuat, mengelola, dan mengkueri tampilan Iceberg. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat, mengelola, dan mengkueri tampilan Iceberg:

  • Membuat tampilan:
    • biglake.views.create di namespace
    • biglake.tables.get di setiap tabel Iceberg yang dirujuk oleh tampilan
  • Tampilan daftar: biglake.views.list di namespace
  • Mendapatkan detail tabel virtual: biglake.views.get pada tabel virtual
  • Mengubah tampilan:
    • biglake.views.update pada tampilan
    • biglake.tables.get di setiap tabel Iceberg yang dirujuk oleh definisi tampilan baru
  • Menghapus tampilan: biglake.views.delete pada tampilan
  • Membuat kueri tampilan:
    • biglake.views.get pada tampilan dan tampilan bertingkat apa pun
    • biglake.tables.get di setiap tabel Iceberg yang dirujuk oleh tampilan
  • Membaca data tabel dalam mode penjualan kredensial: biglake.tables.getData di setiap tabel Iceberg yang direferensikan tampilan
  • Membaca metadata tampilan dan data tabel dalam mode kredensial pengguna akhir: storage.objects.get di bucket Cloud Storage
  • Menulis file metadata tampilan dalam mode kredensial pengguna akhir: storage.objects.create di bucket Cloud Storage

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Tabel berikut memetakan setiap izin tampilan ke operasi endpoint katalog REST Apache Iceberg yang diotorisasi:

Izin Resource Operasi endpoint Disertakan dalam peran bawaan
biglake.views.create Namespace CreateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.get Lihat GetIcebergView, CheckIcebergViewExists roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer
biglake.views.update Lihat UpdateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.delete Lihat DeleteIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.list Namespace ListIcebergViewIdentifiers roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer

Untuk mengetahui informasi selengkapnya, lihat Peran IAM Lakehouse.

Endpoint tampilan yang didukung

Saat mesin menginisialisasi sesi katalog dengan GET /v1/config?warehouse=WAREHOUSE_URI, endpoint katalog REST Apache Iceberg akan mengiklankan endpoint tampilan berikut dalam daftar endpoints. Dalam tabel berikut, {prefix} adalah projects/PROJECT_ID/catalogs/CATALOG_ID.

Metode dan jalur Operasi Deskripsi Izin yang diperlukan
GET /v1/{prefix}/namespaces/{namespace}/views ListIcebergViewIdentifiers Mencantumkan ID tampilan dalam namespace. Mendukung pageToken dan pageSize. Tidak menyertakan tabel. biglake.views.list di namespace
POST /v1/{prefix}/namespaces/{namespace}/views CreateIcebergView Membuat tampilan, menulis file 00000-UUID.metadata.json awal ke Cloud Storage, dan mendaftarkan tampilan. biglake.views.create di namespace
GET /v1/{prefix}/namespaces/{namespace}/views/{view} GetIcebergView Memuat metadata tampilan dan lokasi metadata saat ini. biglake.views.get pada tampilan
POST /v1/{prefix}/namespaces/{namespace}/views/{view} UpdateIcebergView Memvalidasi persyaratan konkurensi optimis dan meng-commit update ke file metadata.json baru. biglake.views.update pada tampilan
DELETE /v1/{prefix}/namespaces/{namespace}/views/{view} DeleteIcebergView Menghapus tampilan dari katalog dan menghapus kebijakan Identity and Access Management (IAM) tingkat tampilannya. biglake.views.delete pada tampilan
HEAD /v1/{prefix}/namespaces/{namespace}/views/{view} CheckIcebergViewExists Memeriksa apakah tampilan ada. biglake.views.get pada tampilan

Tindakan pengelolaan

Anda dapat melakukan tindakan pengelolaan berikut pada tampilan Iceberg:

  • Membuat tampilan: Tentukan tampilan di satu atau beberapa tabel Iceberg menggunakan Spark atau endpoint katalog REST Apache Iceberg (CreateIcebergView).
  • Tampilan daftar: Mencantumkan ID tampilan dalam namespace menggunakan Spark atau endpoint katalog REST Apache Iceberg (ListIcebergViewIdentifiers).
  • Mendapatkan detail tampilan: Periksa skema, definisi SQL, dan properti tampilan menggunakan Spark atau endpoint katalog REST Apache Iceberg (GetIcebergView).
  • Membuat kueri tabel virtual: Jalankan kueri terhadap tabel virtual dari mesin open source yang kompatibel dengan Iceberg seperti Spark.
  • Mengubah tampilan: Ganti definisi tampilan atau perbarui properti tampilan menggunakan Spark atau endpoint katalog REST Apache Iceberg (UpdateIcebergView).
  • Menghapus tampilan: Menghapus tampilan dari katalog menggunakan Spark atau endpoint katalog REST Apache Iceberg (DeleteIcebergView).

Batasan

Tampilan Iceberg memiliki batasan berikut:

  • Khusus mesin open source. Anda dapat membuat, mengelola, dan mengkueri tampilan Iceberg hanya dari mesin open source yang kompatibel dengan Iceberg melalui endpoint katalog REST Apache Iceberg. BigQuery SQL, alat command line bq, konsol Google Cloud , gcloud CLI, dan Terraform tidak mendukung tampilan Iceberg.
  • Jenis katalog yang didukung. Tampilan Iceberg hanya didukung di katalog multi-bucket dan katalog single-bucket. Katalog menolak operasi tampilan pada katalog BigQuery dan katalog gabungan dengan error 400 Bad Request (FAILED_PRECONDITION).
  • Operasi tampilan REST yang tidak didukung.
    • Penggantian nama tampilan (POST /v1/{prefix}/views/rename atau ALTER VIEW ... RENAME TO) tidak didukung. Untuk mengganti nama tampilan, buat tampilan dengan nama baru, lalu hapus tampilan asli.
    • Mendaftarkan file tampilan metadata.json (registerView) yang sudah ada tidak didukung.
    • Tampilan terwujud tidak didukung. Hanya tampilan Iceberg logis yang didukung.
  • Perjalanan waktu pada tampilan. Anda tidak dapat menerapkan TIMESTAMP AS OF atau VERSION AS OF ke ID tampilan. Definisi tampilan dapat menerapkan perjalanan waktu ke tabel pokok yang dikueri. Untuk mengetahui informasi selengkapnya, lihat Membuat tampilan dengan perjalanan waktu pada tabel yang mendasarinya.
  • Lihat lokasi penyimpanan.
    • Di katalog bucket tunggal, lokasi tampilan kustom tidak didukung. Lokasi tampilan harus cocok dengan jalur default NAMESPACE_LOCATION/VIEW_NAME.
    • Dalam katalog multi-bucket, lokasi tampilan kustom harus berada dalam awalan URI penyimpanan namespace dan lokasi penyimpanan yang diizinkan katalog.
    • Setelah Anda membuat tampilan, lokasi penyimpanannya tidak dapat diubah. Upaya untuk menetapkan lokasi yang berbeda akan gagal dengan error 400 Bad Request.

Lihat properti

Tampilan Iceberg mendukung properti tampilan yang ditentukan oleh Apache Iceberg. Tabel berikut menjelaskan cara katalog menangani properti ini:

Properti Nilai default Perilaku
write.metadata.compression-codec gzip Secara default, katalog menulis file .gz.metadata.json yang dikompresi dengan gzip. Tetapkan ke none untuk menulis file .metadata.json yang tidak dikompresi. Nilai ini peka huruf besar/kecil. Anda dapat menetapkan properti ini pada waktu pembuatan atau dengan ALTER VIEW ... SET TBLPROPERTIES.
write.metadata.path VIEW_LOCATION/metadata Diabaikan untuk tampilan. Katalog selalu menulis file metadata tampilan di bagian VIEW_LOCATION/metadata/VERSION-UUID.metadata.json.
version.history.num-entries 10 Harus berupa bilangan bulat positif. Membatasi jumlah entri yang dipertahankan katalog dalam daftar versions dan version-log tampilan. Jika commit melebihi batas ini, katalog akan menghapus entri terlama dan selalu mempertahankan versi saat ini dan versi yang ditambahkan oleh commit. Log versi ditujukan untuk audit dan rollback administratif; Compute Engine tidak mendukung kueri versi tampilan historis dengan SQL.

Langkah berikutnya