Dış tabloyu yönetilen Unity Kataloğu tablosuna dönüştürme

Bu sayfada, ALTER TABLE ... SET MANAGED komutunu veya Katalog Gezgini'ni kullanarak Azure Databricks'da bir dış tablonun Unity Kataloğu yönetilen tablosuna nasıl dönüştürüldüğü açıklanır.

`SET MANAGED` Genel bakış

Dış tabloyu Unity Kataloğu yönetilen tablosuna dönüştürmek için kullanın SET MANAGED . Dönüştürme için (CTAS) de kullanabilirsiniz CREATE TABLE AS SELECT , ancak Databricks aşağıdaki avantajları önerir SET MANAGED :

Okuyucu ve yazıcı kesinti süresini en aza indirir.
Dönüştürme sırasında eşzamanlı yazma işlemlerini işler.
Tablo geçmişini korur.
Ad, ayarlar, izinler ve görünümler de dahil olmak üzere aynı tablo yapılandırmalarını korur.
Dönüştürülmüş bir yönetilen tabloyu dış tabloya geri dönüştürmeyi destekler.
Eski kodun dönüştürmeden sonra çalışmasına izin vermek için yol tabanlı okumaları ve yazmaları yeniden yönlendirir.

Prerequisites

Databricks Runtime 17.0 veya üzeri ya da Sunucusuz işlem kullanmanız gerekir SET MANAGED veya UNSET MANAGED kullanmak için.
Iceberg okumalarının (UniForm) zaten etkin olduğu Unity Catalog tablolarını dönüştürmek için Databricks Runtime 17.2 veya üzeri ya da sunucusuz işlem kullanmanız gerekir TRUNCATE UNIFORM HISTORY.
Azure Databricks okuyucuların ve yazarların Databricks Runtime 15.4 LTS veya üzerini kullanması gerekir. Okuyucularınız veya yazarlarınız 14.3 LTS veya üzerini kullanıyorsa bkz. Databricks Runtime 14.3 LTS veya altındaki okuyucular ve yazarlar için alternatif seçenek.
SET MANAGED Tablonuzda DELTA_TRUNCATED_TRANSACTION_LOG, minReaderVersion=2ve minWriterVersion=7varsa komut bir tableFeatures={..., columnMapping} hatayla başarısız olur. kullanarak tablonuzun bu özelliklere DESCRIBE DETAILsahip olup olmadığını doğrulayabilirsiniz.
Databricks dışındaki istemciler, Unity Kataloğu tarafından yönetilen tablo okuma işlemlerini desteklemelidir. Bkz. Delta istemcileri ile tablolara erişme.
- Tablolarınıza erişen okuyucuların ve yazarların Databricks Runtime mı yoksa Databricks dışı dış mı olduğunu görmek için Access Insights panosunu kullanın.

Dönüştürme işleminden sonra, yol tabanlı okuma ve yazma işlemleri otomatik olarak yeni yönetilen konuma küçük bir performans yüküyle yönlendirilir. Databricks, performans ek yükünü önlemek için tüm yol tabanlı erişimin ad tabanlı erişime geçirilmesini önerir. Bkz. Yol tabanlı yeniden yönlendirme.

Important

Çakışmaları önlemek için, tablonuzda çalışan mevcut OPTIMIZE komut işlerini (sıvı kümeleme, sıkıştırma, ZORDER) iptal edin ve dış tablolarınızı yönetilen tablolara dönüştürürken hiçbir iş zamanlamayın.

Dış tablodan yönetilen tabloya dönüştürme

Important

Catalog Gezgini kullanılarak dış tabloları yönetilen tablolara dönüştürme işlemi Beta sürümündedir.

Katalog Tarayıcısı

Katalog Gezgini'ni kullanarak dönüştürdüğünüzde, ad tabanlı erişim otomatik olarak kullanılır. Şemadaki bir veya daha fazla dış tabloyu aynı anda dönüştürebilirsiniz.

Katalog Gezgini'nde dönüştürmek istediğiniz tabloya veya şemaya gidin.
Bu tablo hakkında (tablo ayrıntı sayfası) veya Bu şema hakkında (şema ayrıntı sayfası) altında İyileştirmeleri keşfet'e tıklayın.
Unity Kataloğu ile yönetilen tablolara neden geçilmeli? iletişim kutusunda Devam'a tıklayın.
Dönüştürmek istediğiniz dış tabloları seçin. İletişim kutusunu bir tablo ayrıntı sayfasından açtıysanız, tablonuz önceden seçilmiştir. Ek tablolar bulmak için arama çubuğunu kullanın. Yönetilen tablolar seçilemez.
Dönüştürme not defteri oluştur'a tıklayın.
İsteğe bağlı olarak, not defteri için bir ad girin. Varsayılan olarak, not defteri giriş klasörünüzde kaydedilir. Gözat’a tıklayın ve farklı bir konuma kaydedin.
Not defterinde en iyi yöntemleri gözden geçirin ve tüm önkoşulları karşıladığınızdan emin olun.
YÖNETILEN Sorgular hücresiniSET çalıştırın.

Hücre çalıştırıldıktan sonra, tablo türü Katalog Gezgini'nde EXTERNAL yerine MANAGED olarak görüntülenir. Durum hemen güncelleştirilmezse sayfayı yenileyin.

SQL

Dış tablonuzda Apache Iceberg okumalarının (UniForm) etkinleştirilip etkinleştirilmediğine bağlı olarak aşağıdaki komutlardan birini çalıştırın. Tablonuzda Apache Iceberg okumalarının (UniForm) etkinleştirilip etkinleştirilmediğini doğrulamak için bkz. Iceberg okumalarının (UniForm) etkinleştirildiğini doğrulama.

Apache Iceberg okumaları (UniForm) etkin olmayan Unity Kataloğu dış tabloları için:
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED;
```
Dönüştürme işleminden sonra, uyumluluk kaygıları olmadan yönetilen tablonuzda Iceberg okumalarını etkinleştirebilirsiniz.
Apache Iceberg okumalarının (UniForm) zaten etkin olduğu Unity Kataloğu dış tabloları için:
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;
```
En iyi tablo performansını ve uyumluluğunu korumak için dahil edin TRUNCATE UNIFORM HISTORY . TRUNCATE UNIFORM HISTORY Yalnızca UniForm Iceberg geçmişini keser ve Delta geçmişini kaldırmaz. Bu komut, kesme sonrasında Iceberg için kısa bir okuma ve yazma kesintisine neden olur.

Veriler kopyalanırken komut kesintiye uğrarsa yeniden başlatın ve kaldığı yerden devam eder.

Warning

Databricks, aynı tabloda eşzamanlı olarak birden çok SET MANAGED komut çalıştırmaktan kaçınmanızı önerir ve bu da tutarsız bir tablo durumuna yol açabilir.

Tablo dönüştürme işleminden sonra, okuma ve yazma akışları başarısız olur. Yol tabanlı yeniden yönlendirmeyi otomatik olarak kullanmak için akışları aynı yapılandırmalarla yeniden başlatın. Okuyucularınızın ve yazarlarınızın yönetilen tabloyla çalıştığını doğrulayın. Bkz . Akış davranışı.

Siz el ile kapatmadığınız sürece tahmine dayalı iyileştirme dönüştürme işleminden sonra otomatik olarak etkinleştirilir. Bkz. Tahmine dayalı iyileştirmenin etkinleştirilip etkinleştirilmediğini doğrulama.

Tahmine dayalı iyileştirme etkinleştirildiğinde, Azure Databricks Unity Kataloğu dış konumunuzdaki verileri 14 gün sonra otomatik olarak siler. Tahmine dayalı optimizasyon kapalıysa, yeni dönüştürülen yönetilen tabloda, 14 gün sonra VACUUM komutunu çalıştırın (Databricks Runtime 17.0 veya üzeri veya Sunucusuz işlem gerektirir).

VACUUM my_converted_table

Note

Bazı durumlarda Unity Kataloğu dış konumunuzdaki veriler, tahmine dayalı iyileştirme etkin olsa bile (örneğin, yönetilen tablonuz sık kullanılmıyorsa veya çok küçükse) 14 gün sonra silinemeyebilir. Böyle durumlarda, önceki verileri kaldırmak için 14 gün sonra el ile komutunu çalıştırın VACUUM .

Azure Databricks yalnızca dış konumdaki verileri siler. Unity Catalog'da Delta işlem günlüğü ve tablo referansı ayrı ayrı tutulur.

Dönüştürmeyi doğrulama

Katalog Tarayıcısı

Sayfayı yenileyin. Ayrıntılar sekmesinde, Bu tablo hakkında altında, tablo TürüYönetilen olarak görüntülenir.

SQL

Dış tablonuzun yönetilen tabloya dönüştürüldüğünü onaylamak için aşağıdaki komutu çalıştırın:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Tablo Type olarak MANAGEDgörüntülenir.

Databricks Runtime 14.3 LTS veya altındaki okuyucular ve yazarlar için alternatif seçenek

Databricks, tüm okuyucuların ve yazarların, tablo geçmişini koruyabilme özelliği de dahil olmak üzere avantajlarından yararlanabilmesi için Databricks Runtime 15.4 LTS veya üzeri sürümlere yükseltilmesini önerir.

Databricks Runtime 14.3 veya altında okuyucularınız veya yazarlarınız varsa kullanmaya SET MANAGED devam edebilirsiniz. Ancak, yönetilen tabloya dönüştürdükten sonra, geçmiş işlemelere zaman damgasına göre (yalnızca sürüme göre) zaman yolculuğu yapamazsınız. 14 günlük pencere içinde dış tabloya geri dönerseniz, dönüştürme yeniden etkinleştirilmeden önceki tarihi işlem kayıtlarına zaman yolculuğu tekrar etkinleştirilir.

Her durumda, zaman damgasına göre Unity Kataloğu dış tablosuna geri dönmek, dönüştürülen Unity Kataloğu yönetilen tablonuzda dönüştürme ve geri alma arasında yapılan hiçbir işleme için çalışmaz.

Databricks Runtime 15.4 LTS veya altı ile dönüştürme işleminden sonra bir tabloya yazmak için özelliğin düşürülmesi inCommitTimestamp gerekir:

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

Yol tabanlı yeniden yönlendirme

Important

Yol tabanlı yeniden yönlendirme Genel Önizleme aşamasındadır. Kaydolmak için bu formu doldurun.

Databricks Runtime 18.1 ve sonraki sürümlerde, bir dış tabloyu Unity Kataloğu yönetilen tablosuna dönüştürdükten sonra, yol tabanlı okuma ve yazma işlemleri önceki dış konuma otomatik olarak yeni yönetilen konuma yönlendirilir. Yol tabanlı yeniden yönlendirme, yönetilen tablolara geçiş için gereken süreyi ve çabayı azaltır çünkü depolama yoluna göre tablolara erişen eski kodun yeniden düzenlemenize gerek kalmadan çalışmaya devam etmesine olanak tanır.

Düşük gecikme süreli kullanım örnekleri için Azure Databricks yol tabanlı erişimi ad tabanlı erişime geçirmenizi önerir. Yol tabanlı yeniden yönlendirme, her yol tabanlı okuma veya yazma için birkaç yüz milisaniye ek yük ekler ve eski Delta günlüklerinin Unity Kataloğu dış konumunuzda etkin kalmasını gerektirir. Ad tabanlı okuma ve yazma işlemleri ek performans yüküne sahip değildir.

Akış davranışı

Yol tabanlı yeniden yönlendirme ile akış için:

Okuma işlemleri Databricks Runtime 18.1 ve sonraki sürümleri için desteklenir.
Yazma işlemleri Databricks Runtime 18.2 ve üzerinde desteklenir.

Dönüştürmeden sonra, önceki tablo konumundan okuma veya önceki tablo konumuna yazmaktan kaçınmak için tüm akış işlerini yeniden başlatmanız gerekir.

Yol tabanlı akış okuma ve yazma işlemleri başarısız olur ve sonraki denetim noktasında bir geçiş mesajıyla durur.

Okumalar için akış şu hatayı oluşturur: 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.
Yazma işlemleri için, dönüştürmeden sonraki ilk mikro toplu işlem şu hatayı oluşturur: Operation not allowed: STREAMING WRITE cannot be performed on a table with redirect feature. The no redirect rules are not satisfied [].

Hataları çözmek için akışları aynı yapılandırmalarla yeniden başlatın. Yol tabanlı erişim otomatik olarak yönetilen tabloya yönlendirilir.

Sınırlama

Yol tabanlı yeniden yönlendirme yalnızca geçiş işlemi için geriye dönük uyumluluk sağlar ve Unity Kataloğu yönetilen tablolarına yeni yol tabanlı erişimi etkinleştirmez.

Dönüştürme hatalarını giderme

Bu bölümde, dış tabloları Unity Kataloğu yönetilen tablolarına dönüştürürken karşılaşılan yaygın sorunlar ve bunların nasıl çözüldüğü açıklanmaktadır.

Databricks Runtime sürüm tutarlılığı

Farklı Databricks Runtime sürümleri kullanarak aynı tablonun dönüştürülmesi işlemini çalıştırmaktan veya yeniden denemekten kaçının. Meta veriler sürümler arasında farklı şekilde seri hale getirilebilir ve bu da bir VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED hataya neden olur. Dönüştürme başarısız olursa, her zaman aynı Databricks Runtime sürümünü kullanarak yeniden deneyin.

Dönüştürme sırasında küme kapatma

Kümeniz dönüştürme sırasında kapanırsa, komut DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR ile başarısız olabilir. Dönüştürmeyi sürdürmek için komutunu yeniden deneyin.

Bozuk dış tablo

Dış tablo zaten bozuksa (örneğin, geçerli tablo durumu değilse), dönüştürme , DELTA_TRUNCATED_TRANSACTION_LOGveya DELTA_TXN_LOG_FAILED_INTEGRITYgibi DELTA_STATE_RECOVER_ERRORShatalarla başarısız olabilir. Dönüştürmeyi denemeden önce, dış tabloda gibi DESCRIBE DETAILtemel işlemleri çalıştırabildiğinizi doğrulayın.

Dosya doğrulama hatası

komutu, SET MANAGED tablonun en son anlık görüntüsündeki tüm dosyaların yeni yönetilen tablo konumuna kopyalandığını doğrular. Eksik dosyalar varsa, komut bir DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED hatayla başarısız olur.

Bu sorunu çözmek için:

Geçirilemeyen dosyaları belirlemek için Spark sürücü günlüklerinizi denetleyin.
Bu dosyaların kaynak dış tablo konumunda bulunduğunu ve erişilebilir olduğunu doğrulayın.
komutunu yeniden deneyin ALTER TABLE ... SET MANAGED .

Sorun devam ederse Databricks desteğine başvurun.

Dış tabloya geri dönme

Important

Komutu Databricks UNSET MANAGED Runtime 17.0 veya üzeri ya da Sunucusuz işlem gerektirir.

Dış tabloyu yönetilen tabloya dönüştürdükten sonra 14 gün içinde geri alabilirsiniz.

Geri döndüğünüzde, tablo meta verileri özgün dış konuma işaret eden şekilde güncelleştirilir. Dönüştürmeden sonra yönetilen konuma yapılan tüm yazma işlemleri korunur. Dönüştürme ve geri alma arasında yönetilen konuma yapılan işlemeler sürüme göre zaman yolculuğuna devam eder, ancak zaman damgasına göre değil.

Geri aldıktan yedi gün sonra, Azure Databricks yönetilen konumdaki verileri otomatik olarak siler.

Dış tabloya geri dönmek için aşağıdaki komutu çalıştırın:

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

Geri alma komutu kesintiye uğrarsa, yeniden denemek için yeniden çalıştırın.

Dönüştürmeye benzer şekilde geri döndükten sonra akış işlerinizi de yeniden başlatmanız gerekir.

Geri alma işlemini doğrulama

Dönüştürmenizin geri getirildiğini onaylamak için aşağıdaki komutu çalıştırın:

DESCRIBE EXTENDED catalog_name.schema_name.table_name

Tablo Type olarak EXTERNALgörüntülenir.

Tabloyu Catalog Explorer'da görüntülüyorsanız sayfayı yenileyin. Ayrıntılar sekmesinde, Bu tablo hakkında'nın altında Tür tablosu olarak EXTERNALgörüntülenir.

Kapalı kalma süresi ve veri kopyalama süreleri

SET MANAGED komutu, DEEP CLONE gibi alternatif yaklaşımlara kıyasla kapalı kalma süresini en aza indirir veya ortadan kaldırır. Dönüştürme işlemi iki adımlı bir yaklaşım kullanır:

İlk veri kopyalama (kapalı kalma süresi yok): Tablo verileri ve Delta işlem günlüğü dış konumdan yönetilen konuma kopyalanır. Okuyucular ve yazarlar, devam eden işlemleri etkilemeden normal şekilde çalışmaya devam eder.
Yönetilen konuma geçin (kısa kapalı kalma süresi): İlk adım sırasında dış konuma yapılan işlemeler yönetilen konuma taşınır ve tablo meta verileri yeni yönetilen konumu kaydedecek şekilde güncelleştirilir. Bu adım sırasında, dış konuma yapılan tüm yazma işlemleri geçici olarak engellenir ve yazma kesintisine neden olur. Databricks Runtime 16.1 veya üzerinde okuyucular kapalı kalma süresi yaşamaz; Databricks Runtime 15.4'te okuyucular kapalı kalma süresiyle karşılaşabilir.

Tahmini kapalı kalma süresi:

Tablo boyutu	Önerilen küme boyutu	Veri kopyalama zamanı	Okuyucu ve yazıcı çalışmama süresi
100 GB veya daha az	32 çekirdekli / Ekstra Büyük SQL veri ambarı	Yaklaşık 6 dk veya daha az	Yaklaşık 1-2 dakika veya daha az
1 Terabayt (TB)	64 çekirdekli / 2X-Large SQL deposu	Yaklaşık 30 dk	~1-2 dk
10 TB (terabayt)	256 çekirdekli / 4X Büyük SQL ambarı	Yaklaşık 1,5 saat	~1-5 dk

Tahminlerde 0,5-2 GB/CPU çekirdeği/dakika aktarım hızı varsayılır.

Note

Kapalı kalma süresi, dosya boyutu, dosya sayısı ve işleme sayısı gibi faktörlere göre farklılık gösterebilir.

Sınırlama

Dönüştürmeden sonra akış işlerini yeniden başlatmanız gerekir. Bkz . Akış davranışı.
Dönüştürmeden sonra ama geri almadan önce yapılan işlemeler için tablo geçmişi sürüme göre zaman yolculuğuna izin verir, ancak zaman damgasına göre izin vermez.
Delta Sharing komutuyla SET MANAGED tam olarak uyumlu değil. Açık Delta Paylaşımı beklendiği gibi çalışır, ancak Databricks-Databricks paylaşımı alıcı tablosunun yönetilen konumunu otomatik olarak güncelleştirmez. Alıcı, tablo yeniden paylaşılana kadar eski konumdan okumaya devam eder. Tabloyu yeniden paylaşabilmek için:
```
ALTER SHARE <share_name> REMOVE TABLE <table_name>;
ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;
```
Unity Kataloğu meta veri deponuzun, kataloğunuzun veya şemanızın varsayılan yönetilen konumu dış tablonun depolama konumundan farklı bir bulut bölgesindeyse, bulut sağlayıcınızdan bölgeler arası ek veri aktarım maliyetlerine neden olabilirsiniz.

Şemanızın, kataloğunuzun ve meta veri deponuzun konumlarını doğrulamak için:
```
DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-05-03

Dış tabloyu yönetilen Unity Kataloğu tablosuna dönüştürme

SET MANAGED Genel bakış

Prerequisites

Dış tablodan yönetilen tabloya dönüştürme

Katalog Tarayıcısı

SQL

Dönüştürmeyi doğrulama

Katalog Tarayıcısı

SQL

Databricks Runtime 14.3 LTS veya altındaki okuyucular ve yazarlar için alternatif seçenek

Yol tabanlı yeniden yönlendirme

Akış davranışı

Sınırlama

Dönüştürme hatalarını giderme

Databricks Runtime sürüm tutarlılığı

Dönüştürme sırasında küme kapatma

Bozuk dış tablo

Dosya doğrulama hatası

Dış tabloya geri dönme

Geri alma işlemini doğrulama

Kapalı kalma süresi ve veri kopyalama süreleri

Sınırlama

Geri Bildirim

Ek kaynaklar

`SET MANAGED` Genel bakış