`SYNC`

發行項
12/27/2024

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

使用 SYNC 命令，將 Hive Metastore 中的外部 tables 升級為 Unity Catalog中的外部 tables。您還可以使用 SYNC，將儲存在 Databricks 工作區儲存（有時稱為 DBFS root）之外的 Hive 管理的 tables 升級為 Unity Catalog中的外部 tables。您無法使用它來升級儲存在工作區存儲中的 Hive 受控 tables。若要升級這些tables，請使用CREATE TABLE CLONE。

您可以使用 SYNC，從現有的 Hive 中繼存放區 tables 以及修改 Hive 中繼存放區中的來源 tables 時 update Unity Catalogtables，在 Unity Catalog 中建立新的 tables。

SYNC 命令可以在 schema 層級使用 SYNC SCHEMA 語法執行，或針對個別 table 使用 SYNC TABLE 語法執行。

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

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

重要

執行 SYNC 命令時，SET TBLPROPERTIES 操作會新增一個 table 屬性，該屬性指出目標 Unity Catalog 的外部 table 參考。此作業會計算新的 Delta 快照集，並將新專案新增至 table Delta log，寫入到雲端儲存中的目標 table 路徑。

語法

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

Parameters

SCHEMA

SYNC schema內的所有 tables。
- target_schema
  
  Unity Catalog 中現有的 schema，用戶有權在其中建立 tables。
- source_schema
  
  hive_metastore catalog中現有的 schema，用戶擁有此 hive_metastorecatalog。
TABLE

SYNC 一個人 table。
- target_table
  
  Unity 中新的或現有的 tableCatalog，用戶有權在其中建立 tablesschema。如果 table 已經存在，將其替換成符合 source_table的版本，並且使用者也必須擁有 table。如果 table 不存在，則會建立它。
- source_table
  
  用戶擁有的 hive_metastore 中的現有 table。
principal

選擇性地將 Unity Catalog 中升級的 tables 的擁有者 set 成 principal。默認擁有者是目前的使用者。
AS EXTERNAL

SYNC 一個由 Hive 管理並存放在 Databricks 工作區儲存空間（有時稱為 DBFS 根目錄）之外的 table 或 schema，將其儲存到 Unity Catalog中的外部 tables。您無法使用 AS EXTERNAL 升級儲存在工作區儲存空間中的 Hive 管理的 tables。
DRY RUN

當指定時，檢查是否可以升級 source_schema 內的 source_table 或 tables，而不需要實際建立或升級目標 tables。如果可以升級 table，命令會傳回 DRY_RUN_SUCCESS。
AS EXTERNAL 啟動 Databricks Runtime 13.2 和更新版本，您可以新增這個選擇性子句，以指定 Hive 中繼存放區中的 Managed tables 升級為 Unity Catalog中的外部 tables。搭配 SYNC SCHEMA使用時，它會套用至所有 tables，包括 source_schema. 中管理的 tables。

傳回

具有以下 columns的報表：

source_schema STRING

來源的名稱 schema。如果來源是不支援的暫存檢視，則 schema 是 NULL。
source_name STRING NOT NULL

來源的名稱 table。
source_type STRING NOT NULL

table的類型：MANAGED 或 EXTERNAL
target_catalog STRING NOT NULL

Unity 中的目標 catalog 已同步至 tableCatalogwhere。
target_schema STRING NOT NULL

Unity Catalogwhere 中的目標 schematable 已同步。
target_name STRING NOT NULL

Unity Catalog 中來源 table 同步到的 table 的名稱。此名稱與來源名稱 table 符合。
status_code STRING NOT NULL

來源 table之 SYNC 命令結果的狀態代碼。
description STRING

關於來源 table的 sync 命令狀態的描述性訊息。

傳回的一般狀態代碼 `SYNC`

SYNC 命令在輸出中提供唯一的 status_code 欄位，用於每個 table 被升級至 Unity Catalog，以顯示升級狀態。一些常見的狀態代碼以及解決這些問題的建議如下：

DRY_RUN_SUCCESS：執行成功。

可以使用 SYNC 命令將 table 升級至 Unity Catalog。
DBFS_ROOT_LOCATION：Table 位於 Databricks 檔案系統根目錄中。

table 位於 Databricks 檔案系統根位置。 Unity Catalog不支援此功能。使用具有選項 [DEEP CLONE] 的 CREATE TABLE 命令，將 table 資料複製到 Unity Catalog 位置。
EXTERNAL_TABLE_IN_MANAGED_LOCATION：外部 table 路徑不能在受控儲存空間下。

外部 table 的路徑位於 Unity Catalog 管理存儲內。如果 table 必須位於受控記憶體之下，請使用具有 DEEP CLONE 選項的 CREATE TABLE 命令，將 table 升級為受控 table，或將 table 位置移出 Unity Catalog 受控記憶體。
HIVE_SERDE：table 不符合從 Hive Metastore 升級到 Unity Catalog的條件。原因：Hive SerDe Table。

Unity Catalog不支援 Hive SerDe tables。將 tables 變更為 Delta 格式，併發出 SYNC 命令以升級。
INVALID_DATASOURCE_FORMAT：未指定或不支持數據源格式。

使用其中一種支持的數據源格式：Delta、Parquet、CSV、JSON、ORC、TEXT
LOCATION_OVERLAP：輸入路徑與其他外部 tables重疊。

table 位置與其他外部的 tables重疊。對於 table 或 remove，請使用不同位置以避免與外部重疊的 tables。
MULTIPLE_EXT_LOCATIONS：輸入路徑包含其他外部位置。

有多個外部位置是提供的 table 路徑的子目錄。請檢查 table 位置內的外部地點是否有必要。
MULTIPLE_TARGET_TABLE：已存在不同的同步 table。每個來源只允許一個目標 tabletable。

原始來源 table 先前已同步至不同的目標 table，但這是不被允許的。若要將 SYNC 強制為不同的 table，可以從來源 table 中 removetable 屬性 upgraded_to，或是 remove 之前從 Unity 同步的 tableCatalog，如果不再需要的話。
NOT_EXTERNAL：Table 沒有資格從 Hive 中繼存放區升級到 Unity Catalog。原因：並非外部的 table。

SYNC 命令僅支援將外部 tables 移轉至 Unity Catalog。對於受控 tables，使用具有 DEEP CLONE 選項的 CREATE TABLE 命令，在 Unity Catalog 中建立受控 table。或者，使用 AS EXTERNAL 子句搭配 SYNC 命令，在 Unity Catalog中建立外部 table。
READ_ONLY_CATALOG：Delta sharing catalog 內的數據是唯讀的，無法修改或刪除。

所選的 catalog 是唯讀的 Delta 共享 catalog。在只讀 catalog 中的 Tables 無法使用 SYNC 命令進行更新。
SUCCESS：Table 已成功同步。
TABLE_ALREADY_EXISTS：目標 table 已經存在。

與所選 table 名稱相同的 table 已存在於 Unity Catalog中。重新命名或 remove Unity Catalog 中現有的 table，然後重新執行 SYNC 命令。
TEMP_TABLE_NOT_SUPPORTED：暫時性的 tables 或 views 不受支持。

暫時 tables 或 views 無法升級至 Unity Catalog。若要使用暫時 tables 或 views，請使用 Unity Catalog中的 SHOW CREATE TABLE 命令，在 Unity Catalog 中重新建立它們。
TIMEOUT：Sync 工作逾時。

sync 命令工作花了 300 秒以上才能完成。以秒為單位增加 spark.databricks.sync.command.task.timeout 至較高的值。預設值為 300。如果錯誤持續發生，請連絡支持人員。
VIEWS_NOT_SUPPORTED：不支援 Views。

在 Unity Catalog中使用 SHOW CREATE TABLE 命令手動重新建立 views。

範例

-- 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
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...

共用方式為

`SYNC`

語法

Parameters

傳回

傳回的一般狀態代碼 `SYNC`

範例

意見反應

其他資源

共用方式為

SYNC

語法

Parameters

傳回

傳回的一般狀態代碼 SYNC

範例

相關文章

意見反應

其他資源

`SYNC`

傳回的一般狀態代碼 `SYNC`