Menggunakan tabel Iceberg dengan OneLake

Di Microsoft OneLake, Anda dapat membuat pintasan ke tabel Apache Iceberg Anda, memungkinkan penggunaannya di berbagai beban kerja Fabric. Fungsionalitas ini dimungkinkan melalui fitur yang disebut virtualisasi metadata, yang memungkinkan tabel Iceberg ditafsirkan sebagai tabel Delta Lake dari perspektif pintasan. Saat Anda membuat pintasan ke folder tabel Iceberg, OneLake secara otomatis menghasilkan metadata Delta Lake yang sesuai (log Delta) untuk tabel tersebut, membuat metadata Delta Lake dapat diakses melalui pintasan.

Meskipun artikel ini mencakup panduan untuk menulis tabel Iceberg dari Snowflake ke OneLake, fitur ini dimaksudkan untuk bekerja dengan tabel Iceberg apa pun dengan file data Parquet.

Membuat pintasan tabel ke tabel Iceberg

Jika Anda sudah memiliki tabel Iceberg di lokasi penyimpanan yang didukung oleh pintasan OneLake, ikuti langkah-langkah ini untuk membuat pintasan dan tabel Iceberg Anda muncul dengan format Delta Lake.

1. Temukan tabel Iceberg Anda. Temukan tempat tabel Iceberg Anda disimpan, yang bisa berada di Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage, atau layanan penyimpanan yang kompatibel dengan S3.

   Catatan

   Jika Anda menggunakan Snowflake dan tidak yakin di mana tabel Iceberg Anda disimpan, Anda dapat menjalankan pernyataan berikut untuk melihat lokasi penyimpanan tabel Iceberg Anda.

   SELECT SYSTEM$GET_ICEBERG_TABLE_INFORMATION('<table_name>');

   Menjalankan pernyataan ini mengembalikan jalur ke file metadata untuk tabel Iceberg. Jalur ini memberi tahu Anda akun penyimpanan mana yang berisi tabel Iceberg. Misalnya, berikut adalah info yang relevan untuk menemukan jalur tabel Iceberg yang disimpan di Azure Data Lake Storage:

   {"metadataLocation":"azure://<storage_account_path>/<path_within_storage>/<table_name>/metadata/00001-389700a2-977f-47a2-9f5f-7fd80a0d41b2.metadata.json","status":"success"}

   Folder tabel Iceberg Anda perlu berisi metadata folder, yang berisi setidaknya satu file yang berakhiran .metadata.json.

2. Di Lakehouse Fabric Anda, buat pintasan baru di area Tables di lakehouse yang tidak mendukung skema.

   Catatan

   Jika Anda melihat skema seperti dbo di bawah folder Tabel lakehouse Anda, maka lakehouse diaktifkan skema dan belum kompatibel dengan fitur ini.

   

3. Untuk jalur target pintasan Anda, pilih folder tabel Iceberg. Folder tabel Iceberg berisi metadata folder dan data .

4. Setelah pintasan dibuat, Anda akan secara otomatis melihat tabel ini tercermin sebagai tabel Delta Lake di lakehouse Anda, siap untuk Anda gunakan di seluruh Fabric.

   

   Jika pintasan tabel Iceberg baru Anda tidak muncul sebagai tabel yang dapat digunakan, periksa bagian Pemecahan Masalah.

Menulis tabel Iceberg ke OneLake menggunakan Snowflake

Jika Anda menggunakan Snowflake di Azure, Anda dapat menulis tabel Iceberg ke OneLake dengan mengikuti langkah-langkah berikut:

1. Pastikan kapasitas Fabric Anda berada di lokasi Azure yang sama dengan instans Snowflake Anda.

   Identifikasi lokasi kapasitas Fabric yang terkait dengan Fabric lakehouse Anda. Buka pengaturan ruang kerja Fabric yang berisi lakehouse Anda.

   

   Di sudut kiri bawah Snowflake Anda di antarmuka akun Azure, periksa wilayah Azure akun Snowflake.

   

   Jika wilayah ini berbeda, Anda perlu menggunakan kapasitas Fabric yang berbeda di wilayah yang sama dengan akun Snowflake Anda.

2. Buka menu untuk area File lakehouse Anda, pilih Properti, dan salin URL (jalur HTTPS) folder tersebut.

   

3. Identifikasi ID penyewa Fabric Anda. Pilih profil pengguna Anda di sudut kanan atas UI Fabric, dan arahkan mouse ke atas gelembung info di samping Nama Penyewa Anda. Salin ID Penyewa.

   

4. Di Snowflake, siapkan anda EXTERNAL VOLUME menggunakan jalur ke folder Files di lakehouse Anda. Informasi selengkapnya tentang menyiapkan volume eksternal Snowflake dapat ditemukan di sini.

   Catatan

   Snowflake mengharuskan skema URL menjadi azure://, jadi pastikan untuk mengubah https:// ke azure://.

   CREATE OR REPLACE EXTERNAL VOLUME onelake_exvol
   STORAGE_LOCATIONS =
   (
       (
           NAME = 'onelake_exvol'
           STORAGE_PROVIDER = 'AZURE'
           STORAGE_BASE_URL = 'azure://<path_to_Files>/icebergtables'
           AZURE_TENANT_ID = '<Tenant_ID>'
       )
   );
   

   Dalam sampel ini, setiap tabel yang dibuat menggunakan volume eksternal ini disimpan di Fabric lakehouse, dalam Files/icebergtables folder .

5. Sekarang setelah volume eksternal Anda dibuat, jalankan perintah berikut untuk mengambil URL persetujuan dan nama aplikasi yang digunakan Snowflake untuk menulis ke OneLake. Aplikasi ini digunakan oleh volume eksternal lainnya di akun Snowflake Anda.

   DESC EXTERNAL VOLUME onelake_exvol;
   

   Output dari perintah ini mengembalikan AZURE_CONSENT_URL properti dan AZURE_MULTI_TENANT_APP_NAME . Catat kedua nilai. Nama aplikasi multipenyewa Azure terlihat seperti <name>_<number>, tetapi Anda hanya perlu mengambil bagiannya <name> .

6. Buka URL persetujuan dari langkah sebelumnya di tab browser baru. Jika Anda ingin melanjutkan, setujui izin aplikasi yang diperlukan, jika diminta.

7. Kembali ke Fabric, buka ruang kerja Anda dan pilih Kelola akses, lalu Tambahkan orang atau grup. Berikan aplikasi yang digunakan oleh volume eksternal Snowflake Anda izin yang diperlukan untuk menulis data ke lakehouse di ruang kerja Anda. Sebaiknya berikan peran Kontributor .

8. Kembali ke Snowflake, gunakan volume eksternal baru Anda untuk membuat tabel Iceberg.

   CREATE OR REPLACE ICEBERG TABLE MYDATABASE.PUBLIC.Inventory (
       InventoryId int,
       ItemName STRING
   )
   EXTERNAL_VOLUME = 'onelake_exvol'
   CATALOG = 'SNOWFLAKE'
   BASE_LOCATION = 'Inventory/';
   

   Dengan pernyataan ini, folder tabel Iceberg baru bernama Inventory dibuat dalam jalur folder yang ditentukan dalam volume eksternal.

9. Tambahkan beberapa data ke tabel Iceberg Anda.

   INSERT INTO MYDATABASE.PUBLIC.Inventory
   VALUES
   (123456,'Amatriciana');
   

10. Terakhir, di area Tabel lakehouse yang sama, Anda dapat membuat pintasan OneLake ke tabel Iceberg Anda. Melalui pintasan itu, tabel Iceberg Anda muncul sebagai tabel Delta Lake untuk dikonsumsi di seluruh beban kerja Fabric.

Pemecahan Masalah

Tips berikut dapat membantu memastikan tabel Iceberg Anda kompatibel dengan fitur ini:

Periksa struktur folder tabel Iceberg Anda

Buka folder Iceberg Anda di alat penjelajah penyimpanan pilihan Anda, dan periksa daftar direktori folder Iceberg Anda di lokasi aslinya. Anda akan melihat struktur folder seperti contoh berikut.

../
|-- MyIcebergTable123/
    |-- data/
        |-- snow_A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- snow_A5WYPKGO_2o_AAIBON_h9Rc_0_1_003.parquet
    |-- metadata/
        |-- 00000-1bdf7d4c-dc90-488e-9dd9-2e44de30a465.metadata.json
        |-- 00001-08bf3227-b5d2-40e2-a8c7-2934ea97e6da.metadata.json
        |-- 00002-0f6303de-382e-4ebc-b9ed-6195bd0fb0e7.metadata.json
        |-- 1730313479898000000-Kws8nlgCX2QxoDHYHm4uMQ.avro
        |-- 1730313479898000000-OdsKRrRogW_PVK9njHIqAA.avro
        |-- snap-1730313479898000000-9029d7a2-b3cc-46af-96c1-ac92356e93e9.avro
        |-- snap-1730313479898000000-913546ba-bb04-4c8e-81be-342b0cbc5b50.avro

Jika Anda tidak melihat folder metadata, atau jika Anda tidak melihat file dengan ekstensi yang ditampilkan dalam contoh ini, maka Anda mungkin tidak memiliki tabel Iceberg yang dihasilkan dengan benar.

Periksa log konversi

Ketika tabel Iceberg divirtualisasi sebagai tabel Delta Lake, folder bernama _delta_log/ dapat ditemukan di dalam folder pintasan. Folder ini berisi metadata format Delta Lake (log Delta) setelah konversi berhasil.

Folder ini juga menyertakan latest_conversion_log.txt file, yang berisi detail keberhasilan atau kegagalan konversi yang dicoba terbaru.

Untuk melihat konten file ini setelah membuat pintasan Anda, buka menu untuk pintasan tabel Iceberg di bawah Area tabel lakehouse Anda dan pilih Tampilkan file.

Anda akan melihat struktur seperti contoh berikut:

Tables/
|-- MyIcebergTable123/
    |-- data/
        |-- <data files>
    |-- metadata/
        |-- <metadata files>
    |-- _delta_log/   <-- Virtual folder. This folder doesn't exist in the original location.
        |-- 00000000000000000000.json
        |-- latest_conversion_log.txt   <-- Conversion log with latest success/failure details.

Buka file log konversi untuk melihat waktu konversi terbaru atau detail kegagalan. Jika Anda tidak melihat file log konversi, konversi tidak dicoba.

Jika konversi tidak dicoba

Jika Anda tidak melihat file log konversi, maka konversi tidak dicoba. Berikut adalah dua alasan umum mengapa konversi tidak dicoba:

• Pintasan tidak dibuat di tempat yang tepat.

  Agar pintasan ke tabel Iceberg dikonversi ke format Delta Lake, pintasan harus ditempatkan langsung di bawah folder Tabel lakehouse yang tidak mendukung skema. Anda tidak boleh menempatkan pintasan di bagian File atau di bawah folder lain jika Anda ingin tabel divirtualisasi secara otomatis sebagai tabel Delta Lake.

  

• Jalur target pintasan bukan jalur folder Iceberg.

  Saat Anda membuat pintasan, jalur folder yang Anda pilih di lokasi penyimpanan target hanya boleh berupa folder tabel Iceberg. Folder ini berisimetadata folder dan data .

  

Batasan dan pertimbangan

Perlu diingat batasan sementara berikut saat Anda menggunakan fitur ini:

• Jenis data yang didukung

  Jenis data kolom Iceberg berikut memetakan ke jenis Delta Lake yang sesuai menggunakan fitur ini.

  Tipe kolom Gunung Es	Jenis kolom Delta Lake	Komentar
  int	integer
  long	long	Lihat Masalah lebar jenis.
  float	float
  double	double	Lihat Masalah lebar jenis.
  decimal(P, S)	decimal(P, S)	Lihat Masalah lebar jenis.
  boolean	boolean
  date	date
  timestamp	timestamp_ntz	Jenis timestamp data Iceberg tidak berisi informasi zona waktu. Jenis timestamp_ntz Delta Lake tidak sepenuhnya didukung di seluruh beban kerja Fabric. Kami merekomendasikan penggunaan tanda waktu dengan zona waktu yang disertakan.
  timestamptz	timestamp	Di Snowflake, untuk menggunakan jenis ini, tentukan timestamp_ltz sebagai jenis kolom selama pembuatan tabel Iceberg. Info selengkapnya tentang jenis data Iceberg yang didukung di Snowflake dapat ditemukan di sini.
  string	string
  binary	binary

• Masalah lebar jenis

  Jika Anda menggunakan Snowflake untuk menulis tabel Iceberg Anda dan tabel berisi jenis INT64kolom , , doubleatau Decimal dengan presisi >= 10, maka tabel Delta Lake virtual yang dihasilkan mungkin tidak dapat dikonsumsi oleh semua mesin Fabric. Anda mungkin melihat kesalahan seperti:

  Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
  

  Kami sedang berupaya memperbaiki masalah ini.

  Solusi sementara: Jika Anda menggunakan UI pratinjau tabel Lakehouse dan melihat masalah ini, Anda dapat mengatasi kesalahan ini dengan beralih ke tampilan Titik Akhir SQL (sudut kanan atas, pilih tampilan Lakehouse, beralih ke Titik Akhir SQL) dan mempratinjau tabel dari sana. Jika Anda kemudian beralih kembali ke tampilan Lakehouse, pratinjau tabel akan ditampilkan dengan benar.

  Jika Anda menjalankan buku catatan atau pekerjaan Spark dan mengalami masalah ini, Anda dapat mengatasi kesalahan ini dengan mengatur spark.sql.parquet.enableVectorizedReader konfigurasi Spark ke false. Berikut adalah contoh perintah PySpark untuk dijalankan di buku catatan Spark:

  spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
  

• Penyimpanan metadata tabel Iceberg tidak portabel

  File metadata tabel Iceberg saling merujuk menggunakan referensi jalur absolut. Jika Anda menyalin atau memindahkan konten folder tabel Iceberg ke lokasi lain tanpa menulis ulang file metadata Iceberg, tabel menjadi tidak dapat dibaca oleh pembaca Iceberg, termasuk fitur OneLake ini.

  Solusi:

  Jika Anda perlu memindahkan tabel Iceberg Anda ke lokasi lain untuk menggunakan fitur ini, gunakan alat yang awalnya menulis tabel Iceberg untuk menulis tabel Iceberg baru di lokasi yang diinginkan.

• Tabel gunung es harus lebih dalam dari tingkat akar

  Folder tabel Iceberg dalam penyimpanan harus terletak di direktori yang lebih dalam dari tingkat wadah atau kontainer. Tabel Iceberg yang disimpan langsung di direktori akar wadah atau kontainer mungkin tidak divirtualisasikan ke format Delta Lake.

  Kami sedang berupaya meningkatkan untuk menghapus persyaratan ini.

  Solusi:

  Pastikan bahwa setiap tabel Iceberg disimpan dalam direktori lebih dalam dari direktori akar wadah atau kontainer.

• Folder tabel Iceberg hanya boleh berisi satu set file metadata

  Jika Anda menjatuhkan dan membuat ulang tabel Iceberg di Snowflake, file metadata tidak dibersihkan. Perilaku ini mendukung UNDROP fitur di Snowflake. Namun, karena pintasan Anda menunjuk langsung ke folder dan folder tersebut sekarang memiliki beberapa set file metadata di dalamnya, kami tidak dapat mengonversi tabel hingga Anda menghapus file metadata tabel lama.

  Saat ini, konversi dicoba dalam skenario ini, yang dapat mengakibatkan konten tabel lama dan informasi skema ditampilkan dalam tabel Delta Lake yang divirtualisasi.

  Kami sedang mengerjakan perbaikan di mana konversi gagal jika lebih dari satu set file metadata ditemukan di folder metadata tabel Iceberg.

  Solusi:

  Untuk memastikan tabel yang dikonversi mencerminkan versi tabel yang benar:

  • Pastikan Anda tidak menyimpan lebih dari satu tabel Iceberg di folder yang sama.
  • Bersihkan konten folder tabel Iceberg setelah menjatuhkannya, sebelum membuat ulang tabel.

• Perubahan metadata tidak segera tercermin

  Jika Anda membuat perubahan metadata pada tabel Iceberg Anda, seperti menambahkan kolom, menghapus kolom, mengganti nama kolom, atau mengubah jenis kolom, tabel mungkin tidak dikonversi kembali hingga perubahan data dibuat, seperti menambahkan baris data.

  Kami sedang mengerjakan perbaikan yang mengambil file metadata terbaru yang benar yang menyertakan perubahan metadata terbaru.

  Solusi:

  Setelah membuat perubahan skema ke tabel Iceberg Anda, tambahkan baris data atau buat perubahan lain pada data. Setelah perubahan itu, Anda harus dapat merefresh dan melihat tampilan terbaru tabel Anda di Fabric.

• Ruang kerja yang diaktifkan skema belum didukung

  Jika Anda membuat pintasan Iceberg di lakehouse yang mendukung skema, konversi tidak terjadi untuk pintasan tersebut.

  Kami sedang berupaya meningkatkan untuk menghapus batasan ini.

  Solusi:

  Gunakan lakehouse yang tidak mendukung skema dengan fitur ini. Anda dapat mengonfigurasi pengaturan ini selama pembuatan lakehouse.

• Batasan ketersediaan wilayah

  Fitur ini belum tersedia di wilayah berikut:

  • Qatar Tengah
  • Norwegia Barat

  Solusi:

  Ruang kerja yang terpasang pada kapasitas Fabric di wilayah lain dapat menggunakan fitur ini. Lihat daftar lengkap wilayah tempat Microsoft Fabric tersedia.

• Tautan privat tidak didukung

  Fitur ini saat ini tidak didukung untuk penyewa atau ruang kerja yang mengaktifkan tautan privat.

  Kami sedang berupaya meningkatkan untuk menghapus batasan ini.

• Batasan ukuran tabel

  Kami memiliki batasan sementara pada ukuran tabel Iceberg yang didukung oleh fitur ini. Jumlah maksimum file data Parquet yang didukung adalah sekitar 5.000 file data, atau sekitar 1 miliar baris, batas mana pun yang ditemui terlebih dahulu.

  Kami sedang berupaya meningkatkan untuk menghapus batasan ini.

• Pintasan OneLake harus wilayah yang sama

  Kami memiliki batasan sementara pada penggunaan fitur ini dengan pintasan yang menunjuk ke lokasi OneLake: lokasi target pintasan harus berada di wilayah yang sama dengan pintasan itu sendiri.

  Kami sedang berupaya meningkatkan untuk menghapus persyaratan ini.

  Solusi:

  Jika Anda memiliki pintasan OneLake ke tabel Iceberg di lakehouse lain, pastikan bahwa lakehouse lainnya dikaitkan dengan kapasitas di wilayah yang sama.

• sakelar penyewa memungkinkan akses eksternal

  Kami memiliki batasan sementara yang mengharuskan "Pengguna dapat mengakses data yang disimpan di OneLake dengan aplikasi eksternal ke Fabric" pengaturan penyewa harus diaktifkan.

  Jika pengaturan penyewa ini dinonaktifkan, virtualisasi tabel Iceberg ke format Delta Lake tidak akan berhasil.

  Solusi:

  Minta agar administrator tenant Fabric Anda, jika memungkinkan, mengaktifkan pengaturan tenant "Pengguna dapat mengakses data yang disimpan di OneLake dengan aplikasi di luar Fabric".

• Tabel Iceberg harus menggunakan mekanisme salin-tulis (bukan gabung-saat-baca)

  Saat ini, tabel Iceberg harus copy-on-write. Ini berarti bahwa file tersebut tidak boleh berisi file penghapusan atau merge-on-read .

  Snowflake saat ini memproduksi copy-on-write Iceberg tables, tetapi penulis Iceberg lainnya mungkin mengikuti pendekatan yang berbeda.

  Kami sedang berupaya mendukung tabel Iceberg merge-on-read.

Konten terkait

• Pelajari selengkapnya tentang keamanan Fabric dan OneLake.
• Pelajari selengkapnya tentang pintasan OneLake.