Mode Kompatibilitas

Penting

Dengan Menggunakan Mode Kompatibilitas, Anda dapat membaca tabel terkelola Unity Catalog, tampilan materialisasi, dan tabel streaming dari sistem eksternal sambil mempertahankan performa optimal di Azure Databricks. Fitur ini secara otomatis menghasilkan versi baca-saja dari tabel Anda yang dapat diakses oleh klien Delta Lake atau Iceberg mana pun.

Gambaran Umum

Saat diaktifkan pada tabel terkelola, tabel streaming, atau tampilan materialisasi, Mode Kompatibilitas menghasilkan versi baca-saja tabel Anda di lokasi yang dipilih. Versi kompatibilitas ini mencakup metadata v1 untuk format Delta Lake dan Iceberg, menyediakan kemampuan berikut:

Interoperabilitas dengan klien Delta Lake apa pun: Baca tabel terkelola Anda, termasuk tabel streaming atau tampilan materialisasi, dari klien seperti Amazon Athena, Snowflake, dan Amazon Redshift langsung dari penyimpanan atau melalui Unity REST API
Interoperabilitas dengan klien Iceberg apa pun: Baca tabel terkelola Anda, termasuk tabel streaming atau tampilan materialisasi, dari klien Iceberg seperti Apache Spark, Apache Trino, dan Snowflake melalui katalog Iceberg REST
Otomatisasi Otomatis dan Lupakan: Mengotomatisasi pembaruan data dan metadata untuk versi kompatibilitas, dengan kemampuan mengonfigurasi interval pembaruan yang mendekati waktu nyata.

Prasyarat

Untuk mengaktifkan Mode Kompatibilitas pada tabel, Anda harus menggunakan Katalog Unity. Hanya tabel streaming Unity Catalog, tampilan termaterialisasi Unity Catalog, dan tabel terkelola Unity Catalog yang didukung. Tabel eksternal Unity Catalog tidak didukung.

Selain itu, verifikasi bahwa Anda memiliki lokasi eksternal yang terdaftar di Katalog Unity dengan pengaturan dan izin yang tepat:

Lokasi target harus ada di akun penyimpanan Anda dan kosong.
Lokasi target atau salah satu folder induknya harus didaftarkan sebagai lokasi eksternal di Katalog Unity.
Anda harus memiliki CREATE EXTERNAL TABLE akses untuk lokasi eksternal.
Lokasi target dan setiap folder induk atau anak tidak boleh digunakan sebagai lokasi Mode Kompatibilitas untuk tabel lain dalam 7 hari terakhir.

Mengaktifkan Mode Kompatibilitas pada tabel

Untuk tabel streaming, tampilan materialisasi, dan kloning dangkal terkelola, atur properti tabel berikut pada waktu pembuatan tabel:

CREATE [STREAMING TABLE | MATERIALIZED VIEW | TABLE] my_catalog.my_schema.my_table
TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Hanya untuk tabel terkelola Unity Catalog, Anda juga dapat mengaktifkan Mode Kompatibilitas saat mengubah tabel yang sudah ada:

-- For existing managed tables
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Dibutuhkan waktu hingga satu jam untuk menghasilkan versi kompatibilitas untuk pertama kalinya. Anda dapat segera menyegarkan tabel secara manual untuk mengonfirmasi bahwa tabel berfungsi.

Nota

Anda harus menentukan nama tabel tiga bagian lengkap (catalog.schema.table_name). Misalnya, untuk users.john.my_table, usersadalah katalog dan john merupakan skema.

Periksa apakah Mode Kompatibilitas diaktifkan

Untuk memverifikasi bahwa Mode Kompatibilitas diaktifkan pada tabel Anda, periksa apakah delta.universalFormat.enabledFormats = 'compatibility' properti tabel ada. Anda dapat melihat properti ini di UI Catalog Explorer pada tab detail untuk tabel Anda.

Anda juga bisa menjalankan perintah SQL berikut ini di buku catatan:

DESC DETAIL my_catalog.my_schema.my_table
DESC EXTENDED my_catalog.my_schema.my_table

Cari properti ini dalam output:

delta.universalFormat.enabledFormats: "compatibility" – Menunjukkan bahwa Mode Kompatibilitas diaktifkan
delta.universalFormat.compatibility.location – Menampilkan lokasi versi Mode Kompatibilitas

Mengonfigurasi interval penyegaran

Untuk tabel terkelola Unity Catalog, Anda dapat mengonfigurasi seberapa sering versi Mode Kompatibilitas di-refresh dengan mengatur interval refresh:

-- Evaluate whether a refresh is needed after every commit (fastest)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '0 MINUTES'
)

-- Refresh hourly (default)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '1 HOUR'
)

Interval penyegaran bawaan adalah 1 HOUR. Mengatur interval refresh di bawah 1 jam tidak disarankan, dan tidak akan membuat refresh terjadi lebih sering. Pengecualiannya adalah ketika Anda mengatur interval refresh ke 0 MINUTES. Dalam hal ini, Azure Databricks memeriksa perubahan setelah setiap penerapan dan memicu refresh jika diperlukan.

Untuk tabel streaming dan tampilan materialisasi, interval refresh tidak diperlukan. 0 MINUTES merupakan nilai defaultnya.

Nota

Perubahan yang berdampak signifikan pada waktu refresh (seperti penggantian nama kolom atau mengaktifkan pellebaran jenis) dilakukan setiap jam terlepas dari interval refresh target.

Penyegaran manual

Untuk memicu refresh versi kompatibilitas secara manual:

REFRESH [TABLE | STREAMING TABLE | MATERIALIZED VIEW] my_catalog.my_schema.my_table SYNC UNIFORM

Penyegaran manual berguna untuk menguji bahwa Mode Kompatibilitas berfungsi dengan benar, atau untuk menjamin bahwa versi kompatibilitas Anda terkini sebelum membaca berikutnya. Namun, menunggu refresh otomatis bisa lebih hemat biaya.

Memantau status pembuatan data dan metadata

Mode Kompatibilitas menghasilkan data dan metadata secara otomatis dan asinkron. Untuk tabel terkelola Unity Catalog, pembuatan terjadi per jam secara default, atau berdasarkan interval refresh yang dikonfigurasi. Untuk tabel streaming dan tampilan materialisasi, pembuatan terjadi setelah pembaruan tabel saat ada commit baru.

Untuk memeriksa apakah data dan metadata telah berhasil dihasilkan:

Gunakan DESCRIBE HISTORY untuk menemukan versi terbaru tabel sumber Anda:
```
DESC HISTORY my_catalog.my_schema.my_table
```
Perintah ini mengembalikan riwayat refresh ke Mode Kompatibilitas, termasuk versi dan tanda waktu Delta Lake. Baris atas berisi versi dan tanda waktu terbaru.
Gunakan DESCRIBE EXTENDED untuk menemukan versi Mode Kompatibilitas yang sesuai:
```
DESC EXTENDED my_catalog.my_schema.my_table
```
Cari bidang di bawah Informasi Kompatibilitas Seragam:
- Versi Refresh Terakhir: Versi Delta Lake yang terakhir diperbarui dengan Mode Kompatibilitas
- Terakhir Diperbarui: Stempel waktu dari pembaruan terakhir
Mode Keselarasan terkini jika versi tabel cocok dengan versi yang ditemukan di langkah 1.
Gunakan DESC HISTORY pada versi kompatibilitas itu sendiri:
```
DESC HISTORY delta.\`<compatibility_location>\`
```
Di Catalog Explorer, lihat bidang metadata untuk versi kompatibilitas. Mode Kompatibilitas adalah yang terbaru jika versi Delta Lake cocok dengan versi yang ditemukan di langkah 3.

Memantau biaya

Pengoptimalan Prediktif menangani kluster komputasi yang melakukan refresh otomatis untuk Mode Kompatibilitas. Untuk melihat biaya terkait, kueri tabel penagihan sistem:

SELECT
  DATE_TRUNC('DAY', start_time) AS day,
  SUM(usage_quantity) AS dbus
FROM
  system.storage.predictive_optimization_operations_history
WHERE
  operation_type = "COMPATIBILITY_MODE_REFRESH"
GROUP BY 1
ORDER BY 1 DESC;

Kueri ini hanya melaporkan penggunaan untuk penyegaran otomatis. Biaya untuk refresh manual dikaitkan dengan komputasi Anda, dan tidak ada cara langsung untuk melacak biaya tersebut secara terpisah. Umumnya, biaya pemicu manual sebanding dengan biaya operasi tulis awal ke tabel asli.

Menghapus file data yang tidak digunakan

Untuk menghapus file data yang tidak digunakan pada versi kompatibilitas tabel Anda, gunakan VACUUM:

VACUUM delta.'<compatibility_mode_location_path>';

Untuk menemukan jalur lokasi Mode Kompatibilitas, gunakan DESCRIBE EXTENDED perintah di Periksa apakah Mode Kompatibilitas diaktifkan. Dalam keluaran, nilai delta.universalFormat.compatibility.location adalah lokasi.

Membaca versi kompatibilitas dari klien eksternal

Anda dapat menggunakan klien Delta Lake atau Iceberg apa pun untuk membaca data dari versi kompatibilitas. Lihat contoh-contoh Amazon Athena dan Snowflake (Pembaca Delta) di bawah ini.

Amazon Athena

Di Editor Kueri Athena, buat tabel eksternal dengan lokasi yang ditentukan:

CREATE EXTERNAL TABLE <table_name>
LOCATION '<compatibility_location>'
TBLPROPERTIES ('table_type' = 'DELTA')

Baca tabel:
```
SELECT * FROM <table_name>
```

Pembaca dari Snowflake Delta Lake

Buat integrasi penyimpanan untuk mengakses lokasi penyimpanan (lihat dokumentasi Snowflake).

Buat tabel eksternal dengan format Delta Lake:

CREATE OR REPLACE EXTERNAL TABLE <table_name>
WITH LOCATION = @<my_location>
FILE_FORMAT = (TYPE = PARQUET)
TABLE_FORMAT = DELTA
AUTO_REFRESH = false
REFRESH_ON_CREATE = false;

Perbarui tabel (pembaruan otomatis tidak didukung untuk format Delta Lake di Snowflake):
```
ALTER EXTERNAL TABLE <table_name> REFRESH;
```
Baca tabel:
```
SELECT * FROM <table_name>;
```

Membaca versi kompatibilitas dari Unity REST API

Tabel dengan Mode Kompatibilitas diaktifkan dapat dibaca berdasarkan nama melalui Unity REST API dengan parameter khusus. Untuk tabel streaming, atur parameter API berikut:

GET /api/2.1/unity-catalog/tables/{full_name}?read_streaming_table_as_managed=true

Untuk tampilan materialisasi, atur parameter API berikut:

GET /api/2.1/unity-catalog/tables/{full_name}?read_materialized_view_as_managed=true

Membaca versi kompatibilitas dari katalog Iceberg REST

Tabel dengan Mode Kompatibilitas diaktifkan dapat dibaca dari klien Iceberg mana pun menggunakan katalog Iceberg REST. Mode Kompatibilitas berfungsi secara otomatis untuk format tabel Delta Lake dan Iceberg.

Persyaratan penyiapan

Aktifkan akses data eksternal di metastore.
Berikan EXTERNAL USE SCHEMA hak istimewa pada skema.
Membuat Token Akses Pribadi (PAT) Azure Databricks.

Konfigurasi Apache Spark

bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-azure-bundle:1.8.0 \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf spark.sql.catalog.catalog_name=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.catalog_name.type=rest \
  --conf spark.sql.catalog.catalog_name.uri=<workspace-url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.catalog_name.token=<PAT> \
  --conf spark.sql.catalog.catalog_name.warehouse=<uc-catalog-name>

Untuk informasi selengkapnya, lihat Menggunakan tabel Iceberg dengan Apache Spark.

Konfigurasi Snowflake

Snowflake menyediakan dua opsi untuk mengakses tabel Mode Kompatibilitas melalui katalog Iceberg REST: melalui database yang ditautkan katalog Snowflake, atau melalui tabel eksternal.

Untuk kedua opsi, pertama-tama konfigurasikan integrasi katalog Snowflake:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Ganti variabel berikut:

<catalog-integration-name>: Nama yang ingin Anda tetapkan untuk katalog yang terdaftar di Snowflake.
<uc-schema-name>: Nama skema di Unity Catalog yang perlu Anda akses.
<uc-catalog-name>: Nama katalog di Unity Catalog yang perlu Anda akses.
<workspace-url>: URL ruang kerja Azure Databricks.
<token>: Token PAT untuk pengguna utama yang mengonfigurasi integrasi.

Database yang Ditautkan ke Katalog

Database yang dikaitkan dengan katalog Snowflake secara otomatis sinkron dengan Unity Catalog untuk mendeteksi skema dan tabel Iceberg. Ini menghilangkan kebutuhan akan refresh metadata manual.

Setelah mengonfigurasi integrasi katalog Snowflake, lihat dokumentasi Snowflake untuk membuat database yang terhubung ke katalog guna mengakses tabel Anda.

Nota

Tabel yang diakses melalui Mode Kompatibilitas bersifat baca-saja. Karena database yang ditautkan ke katalog adalah fitur Snowflake, Databricks merekomendasikan untuk mengacu pada dokumentasi Snowflake mengenai operasi yang didukung pada tabel streaming Azure Databricks, tampilan materialisasi, atau tabel terkelola ketika Mode Kompatibilitas diaktifkan.

Tabel eksternal

Atau, Anda dapat membuat tabel eksternal setelah membuat integrasi katalog Snowflake. Pendekatan ini memerlukan penyegaran metadata secara manual untuk melihat pembaruan.

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-st/mv-name>';

Nonaktifkan Mode Kompatibilitas

Untuk menonaktifkan Mode Kompatibilitas, batalkan atur properti tabel terkait:

-- For UC managed tables
ALTER TABLE my_table UNSET TBLPROPERTIES('delta.universalFormat.enabledFormats')

-- For streaming tables and materialized views
CREATE OR REPLACE [STREAMING TABLE | MATERIALIZED VIEW] my_table
TBLPROPERTIES('delta.universalFormat.enabledFormats' = '')

Peringatan

Membatalkan pengaturan Mode Kompatibilitas segera menghentikan pembuatan data dan metadata. Setelah 7 hari, data dan metadata terkait akan dihapus. Dalam periode 7 hari ini, Anda dapat memulihkan data dan metadata dengan mengaktifkan kembali Mode Kompatibilitas pada tabel yang sama.

Keterbatasan

Akses baca-saja: Versi kompatibilitas bersifat baca-saja. Anda tidak dapat menulis ke versi kompatibilitas.
Tidak ada dukungan RLS/CLS: Anda tidak dapat mengaktifkan Mode Kompatibilitas pada tabel dengan Row-Level Security (RLS) atau Column-Level Security (CLS).
Tidak ada penggantian nama kolom partisi: Penggantian nama kolom partisi tidak didukung pada tabel dengan Mode Kompatibilitas diaktifkan. Penggantian nama kolom data didukung.
Fitur tabel terbatas: Kemampuan berikut ini tidak tersedia dalam versi kompatibilitas:
- Kolom pengurutan
- Kunci primer
- Perjalanan Waktu
- Mengubah aliran data
- Nama kolom dengan karakter khusus (akan diganti namanya)

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-21

Mode Kompatibilitas

Gambaran Umum

Prasyarat

Mengaktifkan Mode Kompatibilitas pada tabel

Periksa apakah Mode Kompatibilitas diaktifkan

Mengonfigurasi interval penyegaran

Penyegaran manual

Memantau status pembuatan data dan metadata

Memantau biaya

Menghapus file data yang tidak digunakan

Membaca versi kompatibilitas dari klien eksternal

Amazon Athena

Pembaca dari Snowflake Delta Lake

Membaca versi kompatibilitas dari Unity REST API

Membaca versi kompatibilitas dari katalog Iceberg REST

Persyaratan penyiapan

Konfigurasi Apache Spark

Konfigurasi Snowflake

Database yang Ditautkan ke Katalog

Tabel eksternal

Nonaktifkan Mode Kompatibilitas

Keterbatasan

Saran dan Komentar

Sumber Daya Tambahan: