SYNC

  • 發行項

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

SYNC此命令可用來將Hive中繼存放區中的外部資料表升級至 Unity 目錄中的外部資料表。 您可以使用它，從現有的 Hive 中繼存放區數據表在 Unity 目錄中建立新的資料表，並在 Hive 中繼存放區中的源數據表變更時更新 Unity 目錄數據表。

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

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

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

重要

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

語法

SYNC { SCHEMA target_schema FROM source_schema |
       TABLE target_table 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。 默認擁有者是目前的使用者。

  • DRY RUN

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

傳回

具有下列資料列的報表：

  • source_schema STRING

    來源架構的名稱。 如果來源是不支援的暫存檢視，則架構 NULL 為 。

  • source_name STRING NOT NULL

    來源資料表的名稱。

  • source_type STRING NOT NULL

    數據表的類型： MANAGED 或 EXTERNAL

  • target_catalog STRING NOT NULL

    Unity 目錄中的目標目錄，其中數據表已同步。

  • target_schema STRING NOT NULL

    Unity 目錄中的目標架構，其中已同步處理數據表。

  • target_name STRING NOT NULL

    同步處理源數據表之 Unity 目錄中的數據表名稱。 此名稱符合源數據表名稱。

  • status_code STRING NOT NULL

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

  • description STRING

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

傳回的一般狀態代碼 SYNC

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

  • DRY_RUN_SUCCESS：執行成功。

    數據表可以使用 命令升級至 Unity 目錄 SYNC 。

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

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

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION：外部數據表路徑不能在受控記憶體下。

    提供給外部數據表的路徑位於 Unity 目錄管理記憶體內。 如果數據表必須位於受控記憶體之下，請使用 CREATE TABLE 命令搭配 DEEP CLONE 選項，將數據表升級為受控數據表，或將數據表位置移出 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 目錄移除先前同步的數據表。

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

    SYNC 命令僅支援將外部數據表移轉至 Unity 目錄。 針對受控數據表，請使用 CREATE TABLE 命令搭配 DEEP CLONE 選項，在 Unity 目錄中建立受控數據表。

  • READ_ONLY_CATALOG:D elta 共用目錄內的數據是唯讀的，無法修改或刪除。

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

  • SUCCESS：已成功同步處理數據表。

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

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

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

    臨時表或檢視表無法升級至 Unity 目錄。 若要使用臨時表或檢視表，請使用 Unity 目錄中的 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 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
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...