將外部資料表轉換成受控 Unity 目錄資料表

本頁說明如何利用 ALTER TABLE ... SET MANAGED 指令或目錄檔案總管，將外部資料表轉換為 Azure Databricks 中 Unity 目錄管理的資料表。

`SET MANAGED` 概述

用 SET MANAGED 來將外部資料表轉換成 Unity 目錄管理的資料表。雖然您也可以使用 CREATE TABLE AS SELECT （CTAS）進行轉換，但 Databricks 建議 SET MANAGED 以下優點：

減少讀者與作者的休息時間。
在轉換過程中處理並行寫入。
保留資料表歷史。
保持相同的表格配置，包括名稱、設定、權限和檢視。
支援將已轉換的管理資料表還原為外部資料表。

Prerequisites

外部數據表的所有讀取器和寫入器都必須使用以名稱為基礎的存取。例如：
```
SELECT * FROM catalog_name.schema_name.table_name;
```
不支援路徑型存取，而且在轉換資料表之後可能會失敗。
你必須使用 Databricks Runtime 17.0 或以上版本或 Serverless 運算才能使用 SET MANAGED 或 UNSET MANAGED。
若要轉換已啟用 Iceberg 讀取（UniForm）的 Unity 目錄資料表，必須使用 Databricks Runtime 17.2 或更高版本或 Serverless 運算來使用 TRUNCATE UNIFORM HISTORY。
Azure Databricks 讀取器和寫入器必須使用 Databricks Runtime 15.4 LTS 或更新版本。如果您的讀取器或寫入器使用 14.3 LTS 或以下版本，請參閱 Databricks Runtime 14.3 LTS 或以下讀取器和寫入器的替代選項。
如果您的資料表具有SET MANAGED、DELTA_TRUNCATED_TRANSACTION_LOG和minReaderVersion=2，則minWriterVersion=7命令會失敗並顯示tableFeatures={..., columnMapping}錯誤。你可以用 DESCRIBE DETAIL來驗證你的表格是否具備這些屬性。
外部（非 Databricks）客戶端必須支援對 Unity 目錄受控數據表的讀取。請參閱使用 Delta 用戶端讀取資料表。
- 使用 Access Insights 儀表板來查看存取您資料表的讀取者和寫入者是否為 Databricks Runtime 或外部的非 Databricks 系統。

Important

若要避免衝突，請取消在數據表上作業的任何現有 OPTIMIZE 命令作業（liquid clustering， compaction， ZORDER），而且當您將外部數據表轉換成 Managed 數據表時，請勿排程任何作業。

從外部資料表轉換為管理資料表

Important

使用 Catalog Explorer 將外部資料表轉換為受管理資料表目前仍處於測試階段。

目錄檢視器

使用目錄檔案總管轉換時，會自動使用基於名稱的存取權限。你可以一次轉換一個或多個位於模式中的外部資料表。

在 Catalog 瀏覽器中，前往你想轉換的表格或模式。
在 「關於此表 」（表詳細頁面）或「 關於此結構 」（結構詳細頁面）中，點選 「探索優化」。
在「 為什麼要遷移到 Unity Catalog 管理的資料表？」 對話框中，點擊繼續。
選擇你想轉換的外部表格。如果你從表格詳細頁面開啟對話框，你的表格會被預先選取。請使用搜尋欄尋找更多表格。管理資料表無法選擇。
點擊 建立轉換筆記本。
可選擇輸入筆記本名稱。預設情況下，筆記本會被儲存在你的主資料夾。點擊瀏覽以儲存到其他位置。
在筆記本中檢視最佳實務，並確認你符合所有先決條件。
執行 SET MANAGED Queries 儲存格。

儲存格執行後，資料表類型會在目錄總管中顯示為 MANAGED 而非 EXTERNAL 。如果狀態沒有立即更新，請重新整理頁面。

SQL

根據你的外部資料表是否啟用了 Apache Iceberg 讀取（UniForm），請執行以下其中一個指令。請參閱「確認 Iceberg 讀取（UniForm）是否啟用」以確認你的資料表是否啟用了 Apache Iceberg 讀取（UniForm）。

針對未啟用 Apache Iceberg 讀取（UniForm）的 Unity 目錄外部資料表：
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED;
```
轉換後，您可以在受管資料表上啟用 Iceberg 讀取，而不需要相容性問題。
對於已啟用 Apache Iceberg 讀取（UniForm）的 Unity 目錄外部資料表：
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;
```
包含 TRUNCATE UNIFORM HISTORY 以維持最佳資料表效能與相容性。 TRUNCATE UNIFORM HISTORY 僅截斷 UniForm Iceberg 歷史，並未刪除 Delta 歷史。此命令在資料截斷後，會導致 Iceberg 出現短暫的讀取和寫入停機時間。

如果在複製資料時指令中斷，請重新啟動指令，然後從上次停止的地方繼續。

Warning

Databricks 建議避免在同一個資料表上同時執行多個 SET MANAGED 指令，這可能導致資料表狀態不一致。

表格轉換之後，您必須：

重新啟動使用外部資料表的所有串流工作（讀取或寫入），以避免從先前的位置讀取或寫入。停止目前的工作，並用相同設定開始新的工作。
確認你的讀者和作者是否使用受管理的表格。

預測優化在轉換後會自動啟用，除非你手動關閉它。請參閱驗證是否啟用預測優化。

啟用預測優化後，Azure Databricks 會在 14 天後自動刪除 Unity 目錄外部位置中的資料。若停用了預測優化，則在14天後於新轉換的管理資料表上執行 VACUUM（需使用Databricks Runtime 17.0或更新版本或無伺服器運算）。

VACUUM my_converted_table

Note

在某些情況下，即使啟用預測優化，Unity Catalog 外部位置的資料可能在 14 天後仍未被刪除——例如，如果您的管理資料表不常用或規模非常小。這種情況下，請在14天後手動執行 VACUUM ，移除先前的資料。

Azure Databricks 只會刪除外部位置中的資料。會保留 Delta 交易記錄和 Unity Catalog 中資料表的參考。

驗證轉換

目錄檢視器

重新整理頁面。在「關於此表格」的細節標籤中，表格類型顯示為已管理。

SQL

執行以下指令以確認你的外部資料表已轉換為受管理資料表：

DESCRIBE EXTENDED catalog_name.schema_name.table_name

表格 Type 顯示為 MANAGED。

Databricks Runtime 14.3 LTS 或以下讀取器和寫入器的替代選項

Databricks 建議將所有讀寫器升級至 Databricks Runtime 15.4 LTS 或以上版本，以充分利用 SET MANAGED，包括保留資料表歷史的能力。

如果你有使用 Databricks Runtime 14.3 或以下版本的讀寫者，你仍然可以使用 SET MANAGED。然而，轉換成受管理資料表後，你無法依照時間戳記進行時間旅行以訪問歷史提交，只能僅依版本執行。如果你在 14 天的窗口期內將外部資料表回滾，那麼回到轉換前的歷史提交的功能將會重新啟用。

在所有情況下，嘗試以時間戳回滾至 Unity Catalog 外部資料表將無法有效，這不適用於在轉換和回滾之間對已轉換的 Unity Catalog 管理資料表所做的任何提交。

使用 Databricks Runtime 15.4 LTS 或以下版本轉換之後寫入數據表時，需要卸除 inCommitTimestamp 此功能：

ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

轉換失敗故障排除

本節說明將外部資料表轉換成 Unity 目錄受控資料表時的常見問題，以及如何解決這些問題。

Databricks 執行時版本一致性

避免使用不同的 Databricks Runtime 版本執行或重試相同資料表的轉換。不同版本之間中繼資料的序列化方式可能不同，這會導致 VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILED 的失敗。如果轉換失敗，請務必使用相同的 Databricks Runtime 版本重試。

轉換過程中叢集關閉

如果叢集在轉換期間關閉，則命令可能會失敗，並產生 DELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERROR。重試命令以繼續轉換。

損毀的外部資料表

若外部資料表已損壞（例如資料表狀態無效），轉換可能會因錯誤 DELTA_TRUNCATED_TRANSACTION_LOG如、 DELTA_TXN_LOG_FAILED_INTEGRITY、 DELTA_STATE_RECOVER_ERRORS或而失敗。在嘗試轉換前，請確認你能在外部資料表上執行基本操作，例如 DESCRIBE DETAIL。

檔案驗證失敗

此 SET MANAGED 指令會驗證資料表最新快照中的所有檔案是否已複製到新的管理資料表位置。若有任何檔案遺失，指令會 DELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILED 錯誤失敗。

若要解決此問題：

檢查你的 Spark 驅動程式日誌，找出哪些檔案無法被遷移。
確認這些檔案是否存在於來源外部資料表位置且可存取。
重新嘗試指令 ALTER TABLE ... SET MANAGED 。

如果問題持續，請聯絡 Databricks 客服。

還原至外部資料表

Important

此 UNSET MANAGED 命令需 Databricks Runtime 17.0 版本或以上，或無伺服器運算。

將外部數據表轉換成 Managed 數據表之後，您可以在 14 天內復原。

當你恢復時，資料表的元資料會被更新，以指向原本的外部位置。轉換後對受管理位置的所有寫入都會被保留。在轉換與回滾之間提交到受管理位置的提交，依版本仍可進行回溯，但無法依時間戳記回溯。

回滾七天後，Azure Databricks 會自動刪除受管理位置的資料。

若要回復至外部資料表，請執行下列命令：

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

如果回滾指令被中斷，請重執行以重試。

回滾後你也必須重新啟動串流工作，類似於轉換。

驗證回復

執行以下指令以確認已回復到原轉換狀態：

DESCRIBE EXTENDED catalog_name.schema_name.table_name

表格 Type 顯示為 EXTERNAL。

如果你正在 Catalog Explorer 中查看表格，請刷新頁面。在「關於此表」的「詳情」標籤中，表類型顯示為 EXTERNAL。

停機時間與資料複製時間

SET MANAGED此指令可將停機時間降至最低或消除，相較於其他方法如 DEEP CLONE。轉換過程採用兩步驟：

初始資料複製（無停機）： 資料表資料與 Delta 交易日誌會從外部位置複製到受管理位置。讀取程序與寫入程序持續運作正常，持續的操作不會受到影響。
切換到受管理位置（短暫停機）： 在第一步中提交到外部位置的紀錄將移至受管理位置，並更新表的中介資料以註冊新的受管理位置。在此階段，所有寫入外部位置的作業都會暫時被阻擋，導致寫入者停機。使用 Databricks 16.1 或更高版本的讀者不會遇到停機;使用 Databricks Runtime 15.4 的讀者可能會遇到停機。

預計停機時間：

資料表大小	建議的叢集大小	數據複製的時間	讀取器和寫入器停機
100 GB 或更少	32核心 / 超大型 SQL 倉庫	~6分鐘或更短	~1-2分鐘或更短
1 TB	64核心 / 超大 SQL 資料倉儲	~30 分鐘	~1-2分鐘
10 結核病	256核心/4X大型SQL倉庫	~1.5 小時	~1-5分鐘

估計假設吞吐量為 0.5-2 GB /CPU 核心/分鐘。

Note

停機時間會因檔案大小、檔案數量及提交次數等因素而異。

已知的限制

串流客戶端： 轉換後必須重新開始任何串流工作。
回滾後的資料表歷史限制： 轉換後但回滾前提交的提交資料表歷史可依版本時間旅行，但無法依時間戳記進行時間旅行。
三角洲共享限制： 此 SET MANAGED 指令與 Delta Sharing 並不完全相容。 Open Delta Sharing 正常運作，但 Databricks 對 Databricks 的共享不會自動更新接收資料表的管理位置。收件者會繼續從舊位置讀取，直到重新共用表格為止。若要重新共用表格：
```
ALTER SHARE <share_name> REMOVE TABLE <table_name>;
ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;
```
多重雲區： 如果你的 Unity Catalog 中繼儲存庫、目錄或結構的預設管理位置與外部資料表的儲存位置位於不同的雲端區域，可能會產生額外的跨區域資料傳輸費用。雲端提供者會在 Databricks 控制範圍之外收取這些費用。

要驗證您綱要、編目和中繼資料庫的位置：
```
DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-15

共用方式為

將外部資料表轉換成受控 Unity 目錄資料表

SET MANAGED 概述

Prerequisites

從外部資料表轉換為管理資料表

目錄檢視器

SQL

驗證轉換

目錄檢視器

SQL

Databricks Runtime 14.3 LTS 或以下讀取器和寫入器的替代選項

轉換失敗故障排除

Databricks 執行時版本一致性

轉換過程中叢集關閉

損毀的外部資料表

檔案驗證失敗

還原至外部資料表

驗證回復

停機時間與資料複製時間

已知的限制

意見反應

其他資源

`SET MANAGED` 概述