Mengubah tabel eksternal menjadi tabel Unity Catalog yang terkelola

Halaman ini menjelaskan cara mengonversi tabel eksternal ke tabel terkelola Katalog Unity di Azure Databricks menggunakan perintah ALTER TABLE ... SET MANAGED atau Catalog Explorer.

`SET MANAGED` Ikhtisar

Gunakan SET MANAGED untuk mengonversi tabel eksternal ke tabel terkelola Unity Catalog. Meskipun Anda juga dapat menggunakan CREATE TABLE AS SELECT (CTAS) untuk konversi, Databricks SET MANAGED merekomendasikan untuk manfaat berikut:

Meminimalkan waktu henti pembaca dan penulis.
Menangani penulisan bersamaan selama konversi.
Mempertahankan riwayat tabel.
Mempertahankan konfigurasi tabel yang sama, termasuk nama, pengaturan, izin, dan tampilan.
Mendukung mengembalikan tabel terkelola yang dikonversi ke tabel eksternal.
Mengalihkan pembacaan dan penulisan berbasis jalur untuk memungkinkan kode warisan berfungsi setelah konversi.

Prerequisites

Anda harus menggunakan Databricks Runtime 17.0 atau lebih tinggi atau komputasi Tanpa Server untuk menggunakan SET MANAGED atau UNSET MANAGED.
Untuk mengonversi tabel Unity Catalog dengan bacaan Iceberg (UniForm) yang sudah diaktifkan, Anda harus menggunakan Databricks Runtime 17.2 atau lebih tinggi atau komputasi Tanpa Server untuk menggunakan TRUNCATE UNIFORM HISTORY.
Azure Databricks pembaca dan penulis harus menggunakan Databricks Runtime 15.4 LTS atau lebih tinggi. Jika pembaca atau penulis Anda menggunakan 14.3 LTS atau di bawah ini, lihat Opsi alternatif untuk pembaca dan penulis di Databricks Runtime 14.3 LTS atau di bawahnya.
Perintah SET MANAGED gagal dengan DELTA_TRUNCATED_TRANSACTION_LOG kesalahan jika tabel Anda memiliki minReaderVersion=2, minWriterVersion=7 dan tableFeatures={..., columnMapping}. Anda dapat memverifikasi apakah tabel Anda memiliki properti ini menggunakan DESCRIBE DETAIL.
Klien eksternal (non-Databricks) harus mendukung pembacaan ke tabel yang dikelola oleh Unity Catalog. Lihat Mengakses tabel dengan klien Delta.
- Gunakan dashboard Access Insights untuk melihat apakah pembaca dan penulis yang mengakses tabel Anda adalah Databricks Runtime atau eksternal non-Databricks.

Setelah konversi, baca dan tulis berbasis jalur secara otomatis dialihkan ke lokasi terkelola baru dengan sedikit pengurangan performa. Databricks merekomendasikan migrasi semua akses berbasis jalur ke akses berbasis nama untuk menghindari overhead performa. Lihat Pengalihan berbasis jalur.

Important

Untuk menghindari konflik, batalkan pekerjaan perintah yang ada OPTIMIZE (pengklusteran cair, pemadatan, ZORDER) yang beroperasi pada tabel Anda, dan jangan jadwalkan pekerjaan apa pun saat Anda mengonversi tabel eksternal Anda ke tabel terkelola.

Mengonversi dari eksternal ke tabel terkelola

Important

Mengonversi tabel eksternal ke terkelola menggunakan Catalog Explorer ada di Beta.

Eksplorer Katalog

Saat Anda mengonversi menggunakan Catalog Explorer, akses berbasis nama digunakan secara otomatis. Anda dapat mengonversi satu atau beberapa tabel eksternal dalam skema pada satu waktu.

Buka tabel atau skema yang ingin Anda konversi di Catalog Explorer.
Di bawah Tentang tabel ini (halaman detail tabel) atau Tentang skema ini (halaman detail skema), klik Jelajahi pengoptimalan.
Dalam dialog Mengapa bermigrasi ke tabel terkelola Katalog Unity? klik Lanjutkan.
Pilih tabel eksternal yang ingin Anda konversi. Jika Anda membuka dialog dari halaman detail tabel, tabel Anda telah dipilih sebelumnya. Gunakan bilah pencarian untuk menemukan tabel tambahan. Tabel terkelola tidak dapat dipilih.
Klik Buat buku catatan konversi.
Secara opsional, masukkan nama untuk buku catatan. Secara default, buku catatan disimpan ke folder beranda Anda. Klik Telusuri untuk menyimpannya ke lokasi lain.
Di buku catatan, tinjau praktik terbaik dan verifikasi bahwa Anda memenuhi semua prasyarat.
Jalankan perintah Kueri TERKELOLASET.

Setelah sel berjalan, tipe tabel ditampilkan sebagai DIKELOLA alih-alih EXTERNAL di Catalog Explorer. Refresh halaman jika status tidak segera diperbarui.

SQL

Bergantung pada apakah tabel eksternal Anda mengaktifkan pembacaan Apache Iceberg (UniForm), jalankan salah satu perintah berikut. Lihat Memverifikasi bahwa pembacaan Iceberg (UniForm) diaktifkan untuk memverifikasi apakah tabel Anda mengaktifkan pembacaan Apache Iceberg (UniForm).

Untuk tabel eksternal Unity Catalog tanpa pengaktifan pembacaan Apache Iceberg (UniForm):
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED;
```
Setelah konversi, Anda dapat mengaktifkan bacaan Iceberg di tabel terkelola Anda tanpa masalah kompatibilitas.
Untuk tabel eksternal Unity Catalog dengan pembacaan Apache Iceberg (UniForm) telah diaktifkan:
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;
```
Sertakan TRUNCATE UNIFORM HISTORY untuk mempertahankan performa dan kompatibilitas tabel yang optimal. TRUNCATE UNIFORM HISTORY memotong sejarah UniForm Iceberg saja dan tidak menghapus riwayat Delta. Perintah ini menghasilkan waktu henti baca dan tulis singkat untuk Iceberg setelah pemangkasan.

Jika perintah terganggu saat menyalin data, mulai ulang dan melanjutkan dari titik terakhir.

Warning

Databricks merekomendasikan agar Anda menghindari menjalankan beberapa SET MANAGED perintah secara bersamaan pada tabel yang sama, yang dapat menyebabkan status tabel yang tidak konsisten.

Setelah konversi tabel, aliran baca dan tulis gagal. Mulai ulang aliran dengan konfigurasi yang sama untuk secara otomatis menggunakan pengalihan berbasis jalur. Pastikan bahwa pembaca dan penulis Anda menggunakan tabel terkelola. Lihat Perilaku streaming.

Pengoptimalan prediktif diaktifkan secara otomatis setelah konversi kecuali Anda menonaktifkannya secara manual. Lihat Memverifikasi apakah pengoptimalan prediktif diaktifkan.

Dengan pengoptimalan prediktif diaktifkan, Azure Databricks secara otomatis menghapus data di lokasi eksternal Katalog Unity Anda setelah 14 hari. Jika pengoptimalan prediktif dimatikan, jalankan VACUUM (memerlukan Databricks Runtime 17.0 atau lebih tinggi atau komputasi Tanpa Server) pada tabel terkelola yang baru dikonversi setelah 14 hari.

VACUUM my_converted_table

Note

Dalam beberapa kasus, data di lokasi eksternal Katalog Unity Anda mungkin tidak dihapus setelah 14 hari, bahkan dengan pengoptimalan prediktif diaktifkan — misalnya, jika tabel terkelola Anda tidak sering digunakan atau sangat kecil. Dalam kasus ini, jalankan VACUUM secara manual setelah 14 hari untuk menghapus data sebelumnya.

Azure Databricks hanya menghapus data di lokasi eksternal. Log transaksi Delta dan referensi ke tabel di Katalog Unity disimpan.

Verifikasi konversi

Eksplorer Katalog

Refresh halaman. Di tab Detail , di bawah Tentang tabel ini, Tipe tabel ditampilkan sebagai Terkelola.

SQL

Jalankan perintah berikut untuk mengonfirmasi bahwa tabel eksternal Anda telah dikonversi ke tabel terkelola:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Tabel Type ditampilkan sebagai MANAGED.

Opsi alternatif untuk pembaca dan penulis di Databricks Runtime 14.3 LTS atau di bawahnya

Databricks merekomendasikan untuk meningkatkan semua pembaca dan penulis ke Databricks Runtime 15.4 LTS atau lebih tinggi untuk memanfaatkan SET MANAGED, termasuk kemampuan untuk mempertahankan riwayat tabel.

Anda masih dapat menggunakan SET MANAGED jika Anda memiliki pembaca atau penulis di Databricks Runtime 14.3 atau di bawahnya. Namun, setelah mengonversi ke tabel terkelola, Anda tidak dapat mengakses versi historis dari commit berdasarkan cap waktu — hanya berdasarkan versi. Jika Anda menggulir kembali ke tabel eksternal dalam rentang waktu 14 hari, perjalanan waktu ke komitmen historis yang dilakukan sebelum konversi akan diaktifkan kembali.

Dalam semua kasus, mengembalikan ke tabel eksternal di Unity Catalog berdasarkan tanda waktu tidak berlaku untuk perubahan apa pun yang dilakukan ke tabel terkelola di Unity Catalog Anda yang telah dikonversi dari konversi hingga pengembalian.

Menulis ke tabel setelah konversi dengan Databricks Runtime 15.4 LTS atau versi yang lebih rendah memerlukan penghapusan fitur inCommitTimestamp.

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Pengalihan berbasis jalur

Important

Pengalihan berbasis jalur ada di Pratinjau Umum. Untuk mendaftar, lengkapi formulir ini.

Dalam Databricks Runtime 18.1 dan yang lebih tinggi, setelah Anda mengonversi tabel eksternal ke tabel terkelola Katalog Unity, pembacaan dan penulisan berbasis jalur ke lokasi eksternal sebelumnya secara otomatis dialihkan ke lokasi terkelola yang baru. Pengalihan berbasis jalur mengurangi waktu dan upaya yang diperlukan untuk bermigrasi ke tabel terkelola karena memungkinkan kode warisan yang mengakses tabel menurut jalur penyimpanan untuk terus bekerja tanpa mengharuskan Anda untuk merefaktor.

Untuk kasus penggunaan latensi rendah, Azure Databricks menyarankan Agar Anda memigrasikan akses berbasis jalur ke akses berbasis nama. Pengalihan berbasis jalur menambahkan beberapa ratus milidetik overhead untuk setiap baca atau tulis berbasis jalur, dan mengharuskan log Delta lama tetap aktif di lokasi eksternal Katalog Unity Anda. Baca dan tulis berbasis nama tidak memberikan beban kinerja tambahan.

Perilaku streaming

Untuk streaming dengan pengalihan berbasis jalur:

Pembacaan didukung di Databricks Runtime 18.1 dan seterusnya.
Operasi tulis didukung di Databricks Runtime 18.2 ke atas.

Setelah konversi, Anda harus memulai ulang semua pekerjaan streaming untuk menghindari membaca dari atau menulis ke lokasi tabel sebelumnya.

Streaming berbasis jalur membaca dan menulis gagal dan berhenti pada titik pemeriksaan berikutnya dengan pesan migrasi:

Ketika membaca, stream menghasilkan kesalahan: DELTA_STREAMING_INTERRUPTED_BY_MANAGED_TABLE_CONVERSION: The table at <path> has been converted to a Unity Catalog managed table. The stream has been stopped to ensure data consistency. Restart the stream and it will automatically resume from the last committed offset using the converted table.
Untuk operasi penulisan, mikro-batch pertama setelah konversi menimbulkan kesalahan: Operation not allowed: STREAMING WRITE cannot be performed on a table with redirect feature. The no redirect rules are not satisfied [].

Untuk mengatasi kesalahan, mulai ulang aliran dengan konfigurasi yang sama. Akses berbasis jalur secara otomatis dialihkan ke tabel terkelola.

Batasan

Pengalihan berbasis jalur memberikan kompatibilitas mundur hanya untuk proses migrasi dan tidak mengaktifkan akses berbasis jalur baru ke tabel terkelola Unity Catalog.

Pemecahan masalah kegagalan konversi

Bagian ini menjelaskan masalah umum saat mengonversi tabel eksternal ke tabel terkelola Unity Catalog dan cara mengatasinya.

Konsistensi versi Runtime Databricks

Hindari menjalankan atau mencoba kembali konversi tabel yang sama menggunakan versi Databricks Runtime yang berbeda. Metadata dapat diserialisasikan secara berbeda antar versi, yang mengakibatkan VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED kegagalan. Jika konversi gagal, selalu coba lagi menggunakan versi Databricks Runtime yang sama.

Pematian kluster selama konversi

Jika kluster Anda dimatikan selama konversi, perintah mungkin gagal dengan DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR. Coba lagi perintah untuk melanjutkan konversi.

Tabel eksternal rusak

Jika tabel eksternal sudah rusak (misalnya, status tabel tidak valid), konversi mungkin gagal dengan kesalahan seperti DELTA_TRUNCATED_TRANSACTION_LOG, , DELTA_TXN_LOG_FAILED_INTEGRITYatau DELTA_STATE_RECOVER_ERRORS. Sebelum mencoba konversi, verifikasi bahwa Anda dapat menjalankan operasi dasar pada tabel eksternal, seperti DESCRIBE DETAIL.

Kegagalan validasi file

Perintah SET MANAGED memvalidasi bahwa semua file dalam rekam jepret terbaru tabel disalin ke lokasi tabel terkelola baru. Jika ada file yang hilang, perintah gagal dengan kesalahan DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED .

Untuk mengatasi masalah ini:

Periksa log driver Spark Anda untuk mengidentifikasi file mana yang tidak dapat dimigrasikan.
Verifikasi bahwa file-file ini ada di lokasi tabel eksternal sumber dan dapat diakses.
Coba lagi perintah ALTER TABLE ... SET MANAGED.

Jika masalah berlanjut, hubungi dukungan Databricks.

Gulung balik ke tabel eksternal

Important

UNSET MANAGED Perintah ini memerlukan Databricks Runtime 17.0 atau lebih tinggi atau komputasi Tanpa Server.

Setelah mengonversi tabel eksternal ke tabel terkelola, Anda dapat mengembalikan dalam waktu 14 hari.

Saat Anda mengembalikan, metadata tabel diperbarui untuk mengarahkan kembali ke lokasi eksternal asli. Semua tulisan yang dibuat ke lokasi terkelola setelah konversi dipertahankan. Commit yang dibuat ke lokasi terkelola antara konversi dan rollback tetap dapat ditelusuri berdasarkan versi, tetapi tidak dengan tanda waktu.

Tujuh hari setelah pemutaran kembali, Azure Databricks secara otomatis menghapus data di lokasi terkelola.

Untuk mengembalikan ke tabel eksternal, jalankan perintah berikut:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Jika perintah putar kembali terganggu, jalankan ulang untuk mencoba kembali.

Anda juga harus memulai ulang pekerjaan streaming setelah melakukan rollback, serupa dengan proses konversi.

Memverifikasi pemutaran kembali

Jalankan perintah berikut untuk mengonfirmasi bahwa konversi Anda telah digulung balik:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Tabel Type ditampilkan sebagai EXTERNAL.

Jika Anda menampilkan tabel di Catalog Explorer, refresh halaman. Di tab Detail , di bawah Tentang tabel ini, Tipe tabel ditampilkan sebagai EXTERNAL.

Waktu henti dan waktu penyalinan data

Perintah SET MANAGED meminimalkan atau menghilangkan waktu henti dibandingkan dengan pendekatan alternatif seperti DEEP CLONE. Proses konversi menggunakan pendekatan dua langkah:

Salinan data awal (tanpa waktu henti): Data tabel dan log transaksi Delta disalin dari lokasi eksternal ke lokasi terkelola. Pembaca dan penulis terus beroperasi secara normal tanpa berdampak pada operasi yang sedang berlangsung.
Beralih ke lokasi terkelola (waktu henti singkat): Penerapan yang dibuat ke lokasi eksternal selama langkah pertama dipindahkan ke lokasi terkelola, dan metadata tabel diperbarui untuk mendaftarkan lokasi terkelola baru. Selama langkah ini, semua penulisan ke lokasi eksternal untuk sementara diblokir, mengakibatkan downtime penulisan. Pembaca di Databricks Runtime 16.1 atau lebih tinggi tidak mengalami waktu henti; pembaca di Databricks Runtime 15.4 mungkin mengalami waktu henti.

Estimasi waktu henti:

Ukuran tabel	Ukuran kluster yang direkomendasikan	Waktu untuk penyalinan data	Masa tidak aktif pembaca dan penulis
100 GB atau kurang	Gudang SQL 32-core / X-Large	~6 menit atau kurang	~1-2 menit atau kurang
1 Terabyte (TB)	Gudang SQL 64-core / 2X-Besar	~30 menit	~1-2 menit
10 Terabyte	256-core / 4X-Besar gudang SQL	~1,5 jam	~1-5 menit

Perkiraan memperkirakan tingkat throughput 0,5-2 GB/inti CPU/menit.

Note

Waktu henti dapat bervariasi berdasarkan faktor seperti ukuran berkas, jumlah berkas, dan jumlah komit.

Batasan

Anda harus memulai ulang pekerjaan streaming apa pun setelah konversi. Lihat Perilaku streaming.
Riwayat tabel untuk commit yang dibuat setelah konversi tetapi sebelum pemulihan memungkinkan perjalanan waktu berdasarkan versi tetapi tidak berdasarkan tanda waktu.
Berbagi Delta tidak sepenuhnya kompatibel dengan perintah SET MANAGED. Fitur Berbagi Delta yang terbuka berfungsi seperti yang diharapkan, tetapi berbagi antara Databricks tidak secara otomatis memperbarui lokasi terkelola dari tabel penerima. Penerima terus membaca dari lokasi lama hingga tabel didistribusikan ulang. Untuk membagikan ulang tabel:
```
ALTER SHARE <share_name> REMOVE TABLE <table_name>;
ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;
```
Jika lokasi terkelola default metastore, katalog, atau skema Unity Catalog Anda berada di wilayah cloud yang berbeda dari lokasi penyimpanan tabel eksternal, Anda mungkin dikenakan biaya transfer data lintas wilayah tambahan dari penyedia cloud Anda.

Untuk memverifikasi lokasi skema, katalog, dan metastore Anda:
```
DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

SELECT * FROM system.information_schema.metastores;
```

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-05-03

Mengubah tabel eksternal menjadi tabel Unity Catalog yang terkelola

SET MANAGED Ikhtisar

Prerequisites

Mengonversi dari eksternal ke tabel terkelola

Eksplorer Katalog

SQL

Verifikasi konversi

Eksplorer Katalog

SQL

Opsi alternatif untuk pembaca dan penulis di Databricks Runtime 14.3 LTS atau di bawahnya

Pengalihan berbasis jalur

Perilaku streaming

Batasan

Pemecahan masalah kegagalan konversi

Konsistensi versi Runtime Databricks

Pematian kluster selama konversi

Tabel eksternal rusak

Kegagalan validasi file

Gulung balik ke tabel eksternal

Memverifikasi pemutaran kembali

Waktu henti dan waktu penyalinan data

Batasan

Saran dan Komentar

Sumber Daya Tambahan:

`SET MANAGED` Ikhtisar