共用方式為

SYNC

  • 發行項

適用於：檢查標示為 [是]， Databricks SQL 檢查標示為 [是]， Databricks Runtime 檢查標示為 [是] Unity 目錄

使用 SYNC 命令，將 Hive 中繼存放區中的外部資料表升級至 Unity 目錄中的外部資料表。 您也可以使用 SYNC，將儲存在 Databricks 工作區記憶體外部的 Hive 受控數據表（有時稱為 DBFS 根目錄）升級至 Unity 目錄中的外部數據表。 您無法使用它來升級儲存在工作區記憶體中的 Hive 受控數據表。 若要升級這些資料表，請使用 CREATE TABLE CLONE。

您可以使用 SYNC 從現有的 Hive 中繼存放區數據表在 Unity 目錄中建立新的資料表，並在修改 Hive 中繼存放區中的源數據表時更新 Unity 目錄數據表。

SYNC 命令可以在架構層級中使用 SYNC SCHEMA 語法執行，也可以針對個別數據表使用 SYNC TABLE 語法執行。

此命令會對它升級的每個源數據表執行寫入作業 （ALTER TABLE），以為其記帳新增一些額外的數據表屬性。 如果是 Delta 數據表，若要執行命令的叢集或 SQL 倉儲必須具有數據表位置的寫入許可權。

在 Databricks Runtime 12.2 LTS 或更新版本中，執行命令之前spark.databricks.sync.command.disableSourceTableWrites，將 Spark 組態trueSYNC設定為 ，即可關閉此行為。 當設定為 true時，SYNC 不會新增數據表屬性，因此可能無法偵測數據表先前是否已升級至 Unity 目錄。 在此情況下，它完全依賴數據表名稱來判斷數據表是否先前已升級至 Unity 目錄。 如果源數據表自上次 SYNC 命令之後已重新命名，用戶必須先手動重新命名目的地數據表，才能在設定為 true時重新執行 SYNC 命令。

重要

執行 SYNC 命令時，SET TBLPROPERTIES 作業會新增數據表屬性，指出目標 Unity 目錄外部資料表參考。 此作業會計算新的 Delta 快照，並將新的條目新增至 Delta 日誌，寫入雲端儲存中目標資料表的路徑。

語法

SYNC { SCHEMA target_schema [AS EXTERNAL] FROM source_schema |
       TABLE target_table [AS EXTERNAL] FROM source_table }
  [SET OWNER principal]
  [DRY RUN]

參數

  • SCHEMA

    SYNC 架構中的所有數據表。

    • target_schema

      Unity 目錄中的現有架構，用戶有權在其中建立數據表。

    • source_schema

      hive_metastore 目錄中的現有架構，由用戶擁有。

  • TABLE

    SYNC 個別數據表。

    • target_table

      Unity 目錄中的新或現有數據表，在架構中，用戶有權在其中建立數據表。 如果資料表已經存在，則會被取代以符合 source_table，並且使用者也必須擁有該資料表。 如果數據表不存在，則會建立數據表。

    • source_table

      由用戶擁有的 hive_metastore 中的現有數據表。

  • principal

    選擇性地將 Unity 目錄中已升級資料表的擁有者設定為 principal。 默認擁有者是目前的使用者。

  • AS EXTERNAL

    SYNC 儲存在 Databricks 工作區記憶體外部的 Hive 受控數據表或架構（有時稱為 DBFS 根目錄）到 Unity 目錄中的外部數據表。 您無法使用 AS EXTERNAL 來升級儲存在工作區記憶體中的 Hive 受控數據表。

  • DRY RUN

    當指定時，檢查是否可以升級 source_table 或 source_schema 內的數據表，而不需要實際建立或升級目標數據表。 如果數據表可以升級，此命令會傳回 DRY_RUN_SUCCESS。

  • AS EXTERNAL 啟動 Databricks Runtime 13.2 和更新版本時，可以新增這個選擇性子句，以指定 Hive 中繼存放區中的 Managed 數據表升級為 Unity 目錄中的外部數據表。 搭配 SYNC SCHEMA使用時，它會套用至所有數據表，包括 source_schema. 中的 Managed 數據表

傳回

具有下列欄位的報表：

  • source_schema STRING

    來源架構的名稱。 在來源是不支援的暫存檢視情況下，架構為 NULL。

  • source_name STRING NOT NULL

    源數據表的名稱。

  • source_type STRING NOT NULL

    數據表的類型：MANAGED 或 EXTERNAL

  • target_catalog STRING NOT NULL

    Unity Catalog 中與資料表同步的目標目錄。

  • target_schema STRING NOT NULL

    Unity Catalog 中的目標架構，其中資料表已同步。

  • target_name STRING NOT NULL

    在 Unity 目錄中與源表同步的數據表名稱。 此名稱符合源數據表名稱。

  • status_code STRING NOT NULL

    源數據表 SYNC 命令結果的狀態代碼。

  • description STRING

    源數據表之同步命令狀態的描述性訊息。

傳回的一般狀態代碼 SYNC

SYNC 命令會在輸出中提供唯一 status_code 欄位，讓每個數據表升級至代表升級狀態的 Unity 目錄。 一些常見的狀態代碼以及解決這些問題的建議如下：

  • DRY_RUN_SUCCESS：執行成功。

    您可以使用 SYNC 命令，將資料表升級至 Unity 目錄。

  • DBFS_ROOT_LOCATION：位於 Databricks 檔案系統根目錄中的數據表。

    數據表位於 Databricks 檔案系統根位置。 Unity 目錄不支援此功能。 使用具有 DEEP CLONE 選項的 CREATE TABLE 命令，將數據表數據複製到 Unity 目錄位置。

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION：外部資料表路徑不能在管理儲存空間下。

    提供給外部數據表的路徑位於 Unity 目錄管理記憶體內。 如果數據表必須位於受控記憶體之下，請使用具有 DEEP CLONE 選項的 CREATE TABLE 命令，將數據表升級為受控數據表，或將數據表位置移出 Unity 目錄受控記憶體。

  • HIVE_SERDE：數據表不符合從Hive中繼存放區升級至 Unity 目錄的資格。 原因：Hive SerDe 數據表。

    Unity 目錄不支援 Hive SerDe 資料表。 將數據表變更為 Delta 格式，併發出 SYNC 命令來升級。

  • INVALID_DATASOURCE_FORMAT：未指定或不支持數據源格式。

    使用其中一種支持的數據源格式：Delta、Parquet、CSV、JSON、ORC、TEXT

  • LOCATION_OVERLAP：輸入路徑與其他外部數據表重疊。

    數據表位置與其他外部數據表重疊。 請針對數據表使用不同的位置，或移除重疊的外部數據表。

  • MULTIPLE_EXT_LOCATIONS：輸入路徑包含其他外部位置。

    有多個外部位置是所提供的數據表路徑的子目錄。 請檢查表格位置中的外部位置是否必要。

  • MULTIPLE_TARGET_TABLE：已存在不同的同步數據表。 每個源數據表只允許一個目標數據表。

    源數據表已經同步到一個之前不被允許的不同目標數據表。 若要將 SYNC 強制至不同的數據表，請從源數據表中移除數據表屬性 upgraded_to，或者，若不再需要，請從 Unity Catalog 中移除先前同步的數據表。

  • NOT_EXTERNAL：數據表不符合從Hive中繼存放區升級至 Unity 目錄的資格。 原因：不是外部數據表。

    SYNC 命令僅支援將外部數據表移轉至 Unity 目錄。 針對受控數據表，請使用具有 DEEP CLONE 選項的 CREATE TABLE 命令，在 Unity 目錄中建立受控數據表。 或者，使用 AS EXTERNAL 子句搭配 SYNC 命令，在 Unity Catalog 中建立外部數據表。

  • READ_ONLY_CATALOG：Delta 共用目錄中的數據是唯讀的，無法修改或刪除。

    選擇的目錄是唯讀的 Delta 分享目錄。 唯讀目錄內的數據表無法使用 SYNC 命令來更新。

  • SUCCESS：資料表成功同步。

  • TABLE_ALREADY_EXISTS：目標數據表已經存在。

    與所選數據表同名的數據表已存在於 Unity 目錄中。 重新命名或移除 Unity 目錄中的現有資料表，然後重新執行 SYNC 命令。

  • TEMP_TABLE_NOT_SUPPORTED：不支持臨時表或視圖。

    臨時表或檢視表無法升級至 Unity 目錄。 若要使用臨時表或檢視表，請使用 Unity Catalog 中的 SHOW CREATE TABLE 命令，在 Unity 目錄中重新建立它們。

  • TIMEOUT：同步工作逾時。

    同步處理命令工作需要 300 秒以上才能完成。 以秒為單位增加 spark.databricks.sync.command.task.timeout 至較高的值。 預設值為 300。 如果錯誤持續發生，請連絡支持人員。

  • VIEWS_NOT_SUPPORTED：不支援視圖。

    使用 Unity 目錄中的 SHOW CREATE TABLE 命令，手動重新建立檢視。

範例

-- Sync an existing hive metastore table hive_metastore.default.my_tbl to a Unity Catalog
-- table named main.default.my_tbl.
> SYNC TABLE main.default.my_tbl FROM hive_metastore.default.my_tbl;
  source_schema source_name source_type target_catalog target_schema target_name status_code description
  ------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
  default       my_tbl      external    main           default       my_tbl      SUCCESS     Table main.default.my_tbl synced.

 -- Sync an existing managed hive metastore table hive_metastore.default.my_tbl to an external table named main.default.my_tbl in Unity Catalog.
 > SYNC TABLE main.default.my_tbl AS EXTERNAL FROM hive_metastore.default.my_tbl;
  source_schema source_name source_type target_catalog target_schema target_name status_code description
  ------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
  default       my_tbl      managed    main           default       my_tbl      SUCCESS     Table main.default.my_tbl synced.

-- SYNC a table in DRY RUN mode to evaluate the upgradability of the hive metastore table.
> SYNC TABLE main.default.my_tbl FROM hive_metastore.default.my_tbl DRY RUN;
  source_schema source_name source_type target_catalog target_schema target_name status_code     description
  ------------- ----------- ----------- -------------- ------------- ----------- --------------- ---------------------------------
  default       my_tbl      external    main           default       my_tbl      DRY_RUN_SUCCESS

-- SYNC all the eligible tables in schema hive_metastore.mydb to a Unity Catalog schema main.my_db_uc.
-- The upgraded tables in main.my_db_uc will be owned by alf@melmak.et
> SYNC SCHEMA main.my_db_uc FROM hive_metastore.my_db SET OWNER `alf@melmak.et`;
  source_schema source_name source_type target_catalog target_schema target_name status_code description
  ------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
  ...

-- DRY RUN mode of SYNC SCHEMA to evaluate all the tables in a schema
-- hive_metastore.mydb for upgrading to Unity Catalog.
> SYNC SCHEMA main.my_db_uc FROM hive_metastore.my_db DRY RUN;
  source_schema source_name source_type target_catalog target_schema target_name status_code     description
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...

-- Sync all tables including managed tables in a schema hive_metastore.mydb
-- as external tables in Unity Catalog.
> SYNC SCHEMA main.my_db_uc AS EXTERNAL FROM hive_metastore.my_db;
  source_schema source_name source_type target_catalog target_schema target_name status_code     description
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...