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

此頁面描述如何使用 ALTER TABLE ... SET MANAGED 命令，將外部數據表轉換成 Azure Databricks 中的 Unity 目錄受控數據表。

`SET MANAGED` 概觀

使用此功能 SET MANAGED 將外部資料表轉換成 Azure Databricks 中的 Unity 目錄受控資料表。 SET MANAGED 提供下列優點：

將讀取器和寫入器停機時間降至最低。
在轉換期間處理並行寫入。
保留數據表歷程記錄。
保留相同的數據表組態，包括相同的名稱、設定、許可權和檢視。
能夠將已轉換的管理資料表回復至外部資料表。

Prerequisites

若要使用表格轉換功能，您必須滿足下列先決條件：

外部數據表的所有讀取器和寫入器都必須使用以名稱為基礎的存取。例如：
```
SELECT * FROM catalog_name.schema_name.table_name;
```
不支援路徑型存取，而且在轉換資料表之後可能會失敗。
你必須使用 Databricks Runtime 17.0 或以上或無伺服器運算，才能使用 SET MANAGED 或 UNSET MANAGED。
若要轉換已啟用 Iceberg reads（UniForm）的 Unity 目錄資料表，必須使用 Databricks Runtime 17.2 或更高版本或無伺服器運算來使用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

此 SET MANAGED 指令可在 Databricks Runtime 17.0 或以上版本及無伺服器運算中取得。

此 TRUNCATE UNIFORM HISTORY 指令可在 Databricks Runtime 17.2 或更高版本及無伺服器運算中提供。

執行下列其中一個命令，將 Unity 目錄外部資料表轉換成 Unity 目錄受控資料表。

針對未啟用 Apache Iceberg 讀取（UniForm）的 Unity 目錄外部資料表：
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED;
```
轉換後，您可以在受管資料表上啟用 Iceberg 讀取，而不需要相容性問題。
針對已啟用 Iceberg 讀取的 Unity Catalog 外部資料表（UniForm）：
```
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 目錄外部位置中的資料也可能不會在 14 天後刪除。例如，如果您的 Unity 目錄受控資料表不常使用，或非常小，則可能不會發生自動刪除。在這些情況下，14 天後，手動執行 VACUUM （需 Databricks Runtime 17.0 或以上或無伺服器運算）在新轉換的管理資料表上移除舊資料。

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

檢查轉換

您可以確認外部資料表已轉換成受控資料表：

DESCRIBE EXTENDED catalog_name.schema_name.table_name

檢查此命令的輸出以確認表格已轉換。表格 Type 應顯示為 MANAGED。

如果您要在「目錄總管」中檢視表格資訊，請重新整理頁面。在 「詳細資料」 標籤的「 關於此表格」下，表格類型應顯示為 MANAGED。

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

Databricks 建議您將所有讀取器和寫入器升級至 Databricks Runtime 15.4 LTS 或更新版本，以利用 SET MANAGED 命令，包括保留數據表歷程記錄的能力。

如果您有具有 Databricks Runtime 14.3 或以下的讀取器或寫入器，您仍然可以使用 SET MANAGED 命令。不過，在轉換成受管控的表格之後，您無法按時間戳前往歷史提交。您只能依版本執行此動作。如果您在 14 天的時間窗口內回復到外部數據表，轉換之前的歷史提交的時間回溯功能將會重新啟用。

在所有情況下，無論 Databricks Runtime 版本如何，根據時間戳回滾至 UC 外部的功能無法對曾在完成轉換到嘗試回滾時之間對已轉換的 UC 管理表所做的任何提交起作用。

使用 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。

回復至外部數據表

Important

此 UNSET MANAGED 指令可在 Databricks Runtime 17.0 或以上版本及無伺服器運算中取得。

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

如果您進行回復，在轉換和回復之間提交到外部位置的變更可以按版本進行時間旅行，但不能按時間戳。復原七天后，將會刪除受控位置中的數據。

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

ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED

如果回復命令中斷，您可以重新執行以重試，類似於 SET MANAGED 命令。

檢查復原

您可以確認轉換已回復。

DESCRIBE EXTENDED catalog_name.schema_name.table_name

檢查此命令的輸出，以確認資料表已回滾。表格 Type 應顯示為 EXTERNAL。

如果您要在「目錄總管」中檢視表格資訊，請重新整理頁面。在 「詳細資料」 標籤的「 關於此表格」下，表格類型應顯示為 EXTERNAL。

在回復至外部表格之後，您也必須重新啟動串流作業，類似於轉換過程。

停機時間和數據複製時間

當讀取器或寫入器在轉換期間存取資料表時，可能會發生停機時間。不過，相較於『DEEP CLONE』命令， SET MANAGED 命令會將讀取器和寫入器的停機時間降到最低或消除。 Databricks Runtime 16.1 或更新版本上的讀取器不會停機。第一個步驟中，當表格數據和增量日誌被複製時，讀取器和寫入器不會受到影響。

在第二個步驟中，無法寫入 Unity Catalog 的外部位置，而在第一次數據複製期間對外部位置進行的提交將會被移到這裡。第二個數據複製步驟會導致 Databricks Runtime 15.4 LTS 或以下的寫入器和讀取器停機。

之後，讀取器和寫入器會移轉至 Unity 目錄受控位置，並在 Unity 目錄中註冊新的受控數據表位置。具有 Databricks Runtime 16.1 或更新版本的用戶將享受無停機時間的效能。

預估停機時間為：

資料表大小	建議的叢集大小	數據複製的時間	讀取器和寫入器停機
100 GB 或更少	32 核心 / DBSQL 小型	~6 分鐘或更少	~1-2 分鐘或更少
1 TB	64 核心 / DBSQL 中型	~30 分鐘	~1-2min
10 結核病	256 核心 / DBSQL x-large	~1.5 小時	~1-5min

估計值假設輸送量速率為 0.5-2GB/CPU 核心/分鐘。

Note

停機時間可能會有所不同。轉換的效能取決於檔案大小、檔案數量和提交次數等因素。

已知的限制

將外部轉換為 Managed 資料表（受控資料表）存在以下的限制：

串流客戶端：轉換之後，您必須重新啟動任何串流作業。
回滾後的表歷史約束：對於 Databricks Runtime 15.4 LTS 或更新版本中的讀取者/寫入者，轉換後但回滾前進行的提交會按版本而非時間戳進行時間檢索。
Delta Sharing 限制：此 SET MANAGED 命令與 Delta Sharing 不完全相容。雖然開放的 Delta Sharing 能如預期運作，但 Databricks 間的共用不會自動更新接收者資料表的管理位置。收件者會繼續從舊位置讀取，直到重新共用表格為止。若要重新共用表格：
```
ALTER SHARE <share_name> REMOVE TABLE <table_name>;
ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;
```
多個雲端區域：如果 Unity 目錄中繼存放區、目錄或架構的預設受控位置位於不同於所轉換外部數據表儲存位置的不同雲端區域，您可以產生額外的跨區域數據傳輸成本。雲端提供者會在 Databricks 控制範圍之外收取這些費用。

若要檢查架構、目錄和中繼存放區的位置，您可以使用下列命令：
```
DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-31

共用方式為

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

SET MANAGED 概觀

Prerequisites

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

檢查轉換

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

疑難排解轉換失敗

Databricks 執行時版本一致性

在轉換過程中關閉叢集

損毀的外部資料表

回復至外部數據表

檢查復原

停機時間和數據複製時間

已知的限制

意見反應

其他資源

`SET MANAGED` 概觀