Bagikan melalui


Legacy UniForm IcebergCompatV1

Penting

Dokumentasi ini telah dihentikan dan mungkin tidak diperbarui. Produk, layanan, atau teknologi yang disebutkan dalam konten ini tidak lagi didukung. Lihat tabel Read Delta dengan klien Iceberg.

Penting

Fitur ini ada di Pratinjau Umum di Databricks Runtime 13.2 ke atas.

Delta Universal Format (UniForm) memungkinkan Anda membaca tabel Delta dengan klien pembaca Iceberg.

UniForm memanfaatkan fakta bahwa Delta Lake dan Iceberg terdiri dari file data Parquet dan lapisan metadata. UniForm secara otomatis menghasilkan metadata Iceberg secara asinkron, tanpa menulis ulang data, sehingga klien Iceberg dapat membaca tabel Delta seolah-olah mereka adalah tabel Iceberg. Satu salinan file data melayani kedua format.

Anda dapat mengonfigurasi koneksi eksternal agar Katalog Unity bertindak sebagai katalog Iceberg. Lihat Baca menggunakan titik akhir katalog Unity Catalog Iceberg.

Catatan

Pembuatan metadata UniForm berjalan secara asinkron pada komputasi yang digunakan untuk menulis data ke tabel Delta, yang dapat meningkatkan penggunaan sumber daya driver.

Persyaratan

Untuk mengaktifkan UniForm, Anda harus memenuhi persyaratan berikut:

Aktifkan Seragam Delta

Penting

Mengaktifkan Delta UniForm memfungsikan fitur tabel Delta IcebergCompatV1, yaitu fitur dari protokol penulisan. Hanya klien yang mendukung fitur tabel ini yang dapat menulis ke tabel berkemampuan UniForm. Anda harus menggunakan Databricks Runtime 13.2 atau lebih tinggi untuk menulis ke tabel Delta dengan fitur ini diaktifkan.

Anda dapat menonaktifkan UniForm dengan membatalkan pengaturan properti tabel delta.universalFormat.enabledFormats. Anda tidak dapat menonaktifkan pemetaan kolom setelah diaktifkan, dan peningkatan ke versi protokol pembaca dan penulis Delta Lake tidak dapat dibatalkan.

Properti tabel berikut memungkinkan dukungan UniForm untuk Iceberg. iceberg adalah satu-satunya nilai yang valid.

'delta.universalFormat.enabledFormats' = 'iceberg'

Anda juga harus mengaktifkan pemetaan kolom dan IcebergCompatV1 untuk menggunakan UniForm. Ini diatur secara otomatis jika Anda mengaktifkan UniForm selama pembuatan tabel, seperti dalam contoh berikut:

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'iceberg');

Jika Anda membuat tabel baru dengan pernyataan CTAS, Anda harus menentukan pemetaan kolom secara manual, seperti dalam contoh berikut:

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

Jika Anda mengubah tabel yang sudah ada, Anda harus menentukan semua properti ini, seperti dalam contoh berikut:

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Ketika Anda pertama kali mengaktifkan UniForm, pembuatan metadata asinkron dimulai. Tugas ini harus diselesaikan sebelum klien eksternal dapat mengkueri tabel menggunakan Iceberg. Lihat Memeriksa status pembuatan metadata Iceberg.

Catatan

Jika Anda berencana menggunakan BigQuery sebagai klien pembaca Iceberg, Anda harus mengatur spark.databricks.delta.write.dataFilesToSubdir ke true di Azure Databricks untuk mengakomodasi persyaratan BigQuery untuk tata letak data.

Lihat Batasan.

Kapan UniForm menghasilkan metadata Iceberg?

Azure Databricks memicu pembuatan metadata Iceberg secara asinkron setelah transaksi penulisan Delta Lake selesai menggunakan komputasi yang sama yang menyelesaikan transaksi Delta. Anda juga dapat memicu pembuatan metadata Iceberg secara manual. Lihat Memicu konversi metadata Iceberg secara manual.

Untuk menghindari latensi tulis yang terkait dengan pembuatan metadata Iceberg, tabel Delta yang sering melakukan komit mungkin menggabungkan beberapa komit Delta ke dalam satu komit Iceberg.

Delta Lake memastikan bahwa hanya satu proses pembuatan metadata Iceberg yang sedang berlangsung kapan saja. Penerapan yang akan memicu proses pembuatan metadata Iceberg bersamaan kedua akan berhasil berkomitmen pada Delta, tetapi mereka tidak akan memicu pembuatan metadata Iceberg asinkron. Ini mencegah latensi kaskade untuk pembuatan metadata untuk beban kerja dengan penerapan yang sering (detik hingga menit di antara penerapan).

Lihat versi tabel Delta dan Iceberg.

Periksa status pembuatan metadata Iceberg

UniForm menambahkan bidang berikut ke Metadata tabel Unity Catalog dan Iceberg untuk melacak status pembuatan metadata:

Bidang metadata Deskripsi
converted_delta_version Versi terbaru tabel Delta di mana metadata Iceberg berhasil dihasilkan.
converted_delta_timestamp Tanda waktu penerapan Delta terbaru yang metadata Iceberg berhasil dihasilkan.

Di Azure Databricks, Anda dapat meninjau bidang metadata ini menggunakan Catalog Explorer. Bidang dan nilai ini juga dikembalikan saat menggunakan REST API untuk mendapatkan tabel.

Lihat dokumentasi untuk klien pembaca Iceberg Anda tentang cara meninjau properti tabel di luar Azure Databricks. Untuk OSS Apache Spark, Anda dapat melihat properti ini menggunakan sintaks berikut:

SHOW TBLPROPERTIES <table-name>;

Memicu konversi metadata Iceberg secara manual

Anda dapat memicu pembuatan metadata Iceberg secara manual untuk versi terbaru tabel Delta. Operasi ini berjalan secara sinkron, yang berarti bahwa ketika selesai, konten tabel yang tersedia di Iceberg mencerminkan versi terbaru tabel Delta yang tersedia saat proses konversi dimulai.

Operasi ini seharusnya tidak diperlukan dalam kondisi normal, tetapi dapat membantu jika Anda mengalami hal berikut:

  • Kluster berakhir sebelum pembuatan metadata otomatis berhasil.
  • Kesalahan atau kegagalan pekerjaan mengganggu pembuatan metadata.
  • Klien yang tidak mendukung pembuatan metadata UniForm Iceberg menulis ke tabel Delta.

Gunakan sintaks berikut untuk memicu pembuatan metadata Iceberg secara manual:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Lihat REPAIR TABLE.

Membaca menggunakan jalur metadata JSON

Beberapa klien Iceberg mengharuskan Anda menyediakan jalur ke file metadata versi untuk mendaftarkan tabel Iceberg eksternal. Setiap kali UniForm mengonversi versi baru tabel Delta ke Iceberg, UniForm membuat file JSON metadata baru.

Klien yang menggunakan jalur JSON metadata untuk mengonfigurasi Iceberg termasuk BigQuery. Lihat dokumentasi untuk klien pembaca Iceberg untuk detail konfigurasi.

Delta Lake menyimpan metadata Iceberg di bawah direktori tabel, menggunakan pola berikut:

<table-path>/metadata/<version-number>-<uuid>.metadata.json

Anda dapat menemukan jalur file ini menggunakan Catalog Explorer. Untuk tabel yang diaktifkan UniForm, detail tabel Delta menyertakan bidang untuk lokasi metadata Iceberg.

Anda juga dapat menggunakan REST API untuk mendapatkan semua detail untuk tabel, termasuk lokasi metadata. Gunakan perintah berikut:

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

Tanggapan mencakup informasi berikut:

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

Penting

Klien pembaca Iceberg berbasis jalur mungkin memerlukan memperbarui dan menyegarkan jalur JSON metadata secara manual untuk membaca versi tabel saat ini. Pengguna mungkin mengalami kesalahan saat mengkueri tabel Iceberg menggunakan versi yang sudah kedaluwarsa karena file data Parquet dihapus dari tabel Delta dengan VACUUM.

Baca menggunakan titik akhir katalog Unity Catalog Iceberg

Beberapa klien Iceberg dapat terhubung ke katalog Iceberg REST. Unity Catalog menyediakan implementasi baca-saja dari Iceberg REST catalog API untuk tabel Delta dengan UniForm diaktifkan menggunakan titik akhir /api/2.1/unity-catalog/iceberg. Lihat spesifikasi Iceberg REST API untuk detail tentang penggunaan REST API ini.

Klien yang diketahui mendukung API katalog Iceberg termasuk Apache Spark, Flink, dan Trino. Anda harus mengonfigurasi akses ke penyimpanan objek cloud yang mendasar yang berisi tabel Delta dengan UniForm diaktifkan. Lihat dokumentasi untuk klien pembaca Iceberg untuk detail konfigurasi.

Anda harus membuat dan mengonfigurasi token akses pribadi Azure Databricks untuk memungkinkan layanan lain terhubung ke Unity Catalog. Lihat Mengotorisasi akses ke sumber daya Azure Databricks.

Berikut ini adalah contoh pengaturan untuk mengonfigurasi OSS Apache Spark untuk membaca UniForm sebagai Iceberg:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity"="org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token":"<your_personal_access_token>",
"spark.sql.catalog.unity.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

Ganti URL lengkap ruang kerja tempat Anda membuat token akses pribadi untuk <api-root>.

Catatan

Saat mengkueri tabel di Unity Catalog menggunakan metode ini, pengidentifikasi objek menggunakan pola berikut:

unity.<catalog-name>.<schema-name>.<table-name>

Pola ini menggunakan skema penamaan tiga tingkat yang sama yang ada di Katalog Unity, tetapi menambahkan awalan tambahan unity.

versi tabel Delta dan Iceberg

Delta Lake dan Iceberg mengizinkan kueri perjalanan waktu menggunakan versi tabel atau tanda waktu yang disimpan dalam metadata tabel.

Secara umum, versi tabel Iceberg dan Delta tidak selaras dengan tanda waktu penerapan atau ID versi. Jika Anda ingin memverifikasi versi tabel Delta mana yang sesuai dengan versi tabel Iceberg tertentu, Anda dapat menggunakan properti tabel yang sesuai yang diatur pada tabel Iceberg. Lihat Memeriksa status pembuatan metadata Iceberg.

Batasan

Keterbatasan berikut ada:

  • UniForm tidak berfungsi pada tabel dengan vektor penghapusan diaktifkan. Lihat Apa itu vektor penghapusan?.
  • Tabel delta dengan UniForm diaktifkan tidak mendukung jenis LIST, MAP, dan VOID.
  • Klien Iceberg hanya dapat membaca dari UniForm. Penulisan tidak didukung.
  • Klien pembaca Iceberg mungkin memiliki batasan individu, terlepas dari Seragam. Lihat dokumentasi untuk klien pilihan Anda.
  • Klien pembaca Iceberg versi 1.2.0 ke bawah tidak mendukung INT96 jenis tanda waktu yang ditulis oleh Apache Spark. Gunakan kode berikut dalam buku catatan yang menulis ke tabel UniForm untuk menghindari batasan ini: spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
  • Versi pratinjau publik dari endpoint Unity Catalog Iceberg tidak dirancang untuk beban kerja produksi skala besar. Anda mungkin mengalami pembatasan tarif jika Melebihi ambang batas 5 kueri per detik.

Fitur Delta Lake berikut berfungsi untuk klien Delta saat UniForm diaktifkan, tetapi tidak memiliki dukungan di Iceberg:

  • Ubah Umpan Data
  • Berbagi Delta