SYNC

適用対象: Databricks SQL Databricks Runtime Unity Catalog のみ

SYNC コマンドを使用して、Hive メタストアの外部テーブルを Unity カタログの外部テーブルにアップグレードします。 また、SYNC を使用して、Databricks ワークスペース ストレージ (DBFS ルートとも呼ばれます) の外部に格納されている Hive マネージド テーブルを Unity Catalog の外部テーブルにアップグレードすることもできます。 ワークスペース ストレージに格納されている Hive マネージド テーブルのアップグレードには使用できません。 これらのテーブルをコピーするには、CREATE TABLE CLONE を使用します。

SYNC を使用すると、既存の Hive メタストア テーブルから Unity Catalog に新しいテーブルを作成できるだけではなく、Hive メタストアのソース テーブルが変更された場合に Unity Catalog を更新することもできます。

SYNC コマンドは、SYNC SCHEMA 構文を使用してスキーマ レベルで実行することも、SYNC TABLE 構文を使用して個々のテーブルに対して実行することもできます。

このコマンドは、アップグレードする各ソース テーブルへの書き込み操作 (ALTER TABLE) を実行し、そのブックキーピング用に新しいテーブル プロパティをいくつか追加します。 Delta テーブルの場合、書き込み操作を実行するには、コマンドを実行するクラスターまたは SQL ウェアハウスが、テーブルの場所への書き込みアクセス権を持っている必要があります。

Databricks Runtime 12.2 LTS 以降では、SYNC コマンドを実行する前に Spark 構成 spark.databricks.sync.command.disableSourceTableWrites を true に設定することで、この動作を無効にできます。 true に設定すると、SYNC は新しいテーブル プロパティを追加しないため、テーブルが以前に Unity Catalog にアップグレードされているかどうかを検出できないことがあります。 その場合は、テーブル名のみを使って、テーブルが以前に Unity Catalog にアップグレードされているかどうかを判断します。 前回の SYNC コマンド以降にソース テーブルの名前が変更されている場合、構成が true のときは、SYNC コマンドを再実行する前に、ユーザーは手動でコピー先テーブルの名前を変更する必要があります。

構文

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 Catalog 内の既存のスキーマ。

  • source_schema

    ユーザーが所有する hive_metastore カタログ内の既存のスキーマ。

• TABLE

  個々のテーブルを SYNC します。

  • target_table

    ユーザーがテーブルの作成を許可されているスキーマ内の Unity Catalog の新規または既存のテーブル。 テーブルが既に存在する場合は、source_table と一致するように置き換えられ、ユーザーもテーブルを所有している必要があります。 テーブルが存在しない場合は、作成されます。

  • source_table

    ユーザーが所有する hive_metastore 内の既存のテーブル。

• principal

  必要に応じて、Unity Catalog のアップグレードされたテーブルの所有者を principal に設定します。 既定の所有者は現在のユーザーです。

• AS EXTERNAL

  Databricks ワークスペース ストレージ (DBFS ルートとも呼ばれます) の外部に格納されている Hive マネージド テーブルまたはスキーマを Unity カタログの外部テーブルに SYNC します。 AS EXTERNAL は、ワークスペース ストレージに格納されている Hive マネージド テーブルのアップグレードには使用できません。

• DRY RUN

  指定した場合、ターゲット テーブルを実際に作成またはアップグレードすることなく、source_table または source_schema 内のテーブルをアップグレードできるかどうかを確認します。 このコマンドにより、テーブルをアップグレードできる場合は DRY_RUN_SUCCESS が返されます。

• AS EXTERNAL Databricks Runtime 13.2 以降、この省略可能な句を追加して、Hive メタストアのマネージド テーブルを Unity Catalog の外部テーブルとしてアップグレードするように指定できます。 SYNC SCHEMA と共に使用すると、source_schema. のマネージド テーブルを含むすべてのテーブルに適用されます。

返品

次の列を含むレポート:

• 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 Catalog 内のテーブルの名前。 この名前は、ソース テーブル名と一致します。

• status_code STRING NOT NULL

  ソース テーブルの SYNC コマンドの結果の状態コード。

• description STRING

  ソース テーブルの同期コマンドの状態に関する説明メッセージ。

SYNC によって返される一般的な状態コード

SYNC コマンドによって、アップグレードの状態を表す Unity Catalog にアップグレードする各テーブルの出力に一意の status_code フィールドが提供されます。 いくつかの一般的な状態コードと、それらに対処するための推奨事項を次に示します。

• DRY_RUN_SUCCESS: ドライ ランに成功しました。

  このテーブルは、SYNC コマンドを使用して Unity Catalog にアップグレードできます。

• DBFS_ROOT_LOCATION: Databricks Filesystem ルートにあるテーブル。

  テーブルは Databricks Filesystem のルートの場所にあります。 これは、Unity Catalog ではサポートされていません。 CREATE TABLE コマンドで DEEP CLONE オプションを使用して、テーブル データを Unity Catalog の場所にコピーします。

• EXTERNAL_TABLE_IN_MANAGED_LOCATION: 外部テーブル パスをマネージド ストレージの下に置くことはできません。

  外部テーブルに指定されたパスは、Unity Catalog 管理ストレージ内にあります。 テーブルがマネージド ストレージの下にある必要がある場合は、CREATE TABLE コマンドで DEEP CLONE オプションを使用してテーブルをマネージド テーブルとしてアップグレードするか、テーブルの場所を Unity Catalog マネージド ストレージの外に移動します。

• HIVE_SERDE: テーブルは、Hive メタストアから Unity Catalog へのアップグレードの対象ではありません。 理由: Hive SerDe テーブル。

  Hive SerDe テーブルは Unity Catalog ではサポートされていません。 テーブルを Delta 形式に変更し、SYNC コマンドを発行してアップグレードします。

• INVALID_DATASOURCE_FORMAT: データソース形式が指定されていないか、サポートされていません。

  サポートされているデータ ソース形式 (Delta、Parquet、CSV、JSON、ORC、TEXT) のいずれかを使用します。

• LOCATION_OVERLAP: 入力パスが他の外部テーブルと重複しています。

  テーブルの場所が、他の外部テーブルと重複しています。 テーブルに別の場所を使用するか、重複する外部テーブルを削除します。

• MULTIPLE_EXT_LOCATIONS: 入力パスに、他の外部の場所が含まれています。

  指定されたテーブル パスのサブディレクトリである複数の外部の場所があります。 テーブルの場所内の外部の場所が必要かどうかを確認します。

• MULTIPLE_TARGET_TABLE: 別の同期テーブルが既に存在します。 ソース テーブルごとに許可されるターゲット テーブルは 1 つだけです。

  ソース テーブルは、別のターゲット テーブルに既に同期されています。これは許可されません。 SYNC を別のテーブルに強制するには、ソース テーブルから table プロパティ upgraded_to を削除するか、以前に同期したテーブルが不要になった場合は Unity Catalog から削除します。

• NOT_EXTERNAL: テーブルは、Hive Metastore から Unity Catalog へのアップグレードの対象ではありません。 理由: 外部テーブルではありません。

  SYNC コマンドでは、Unity Catalog への外部テーブルの移行のみがサポートされます。 マネージド テーブルの場合は、CREATE TABLE コマンドで DEEP CLONE オプションを使用して、Unity Catalog にマネージド テーブルを作成します。 または、SYNC コマンドで AS EXTERNAL 句を使用して、Unity Catalog に外部テーブルを作成します。

• READ_ONLY_CATALOG: Delta Sharing カタログ内のデータは読み取り専用であり、変更または削除することはできません。

  選択したカタログは、読み取り専用の Delta Sharing カタログです。 読み取り専用カタログ内のテーブルは、SYNC コマンドを使用して更新できません。

• SUCCESS: テーブルが正常に同期されました。

• TABLE_ALREADY_EXISTS: ターゲット テーブルは既に存在します。

  選択したテーブルと同じ名前のテーブルが Unity Catalog に既に存在します。 Unity Catalog の既存のテーブルの名前を変更または削除し、SYNC コマンドを再実行します。

• TEMP_TABLE_NOT_SUPPORTED: 一時テーブルまたはビューはサポートされていません。

  一時テーブルまたはビューを Unity Catalog にアップグレードすることはできません。 一時テーブルまたはビューを使用するには、Unity Catalog の SHOW CREATE TABLE コマンドを使用して Unity Catalog でこれらを再作成します。

• TIMEOUT: 同期タスクがタイムアウトしました。

  同期コマンド タスクの完了に 300 秒以上かかりました。 spark.databricks.sync.command.task.timeout をもっと大きな値 (秒単位) に増やします。 既定値は 300 です。 このエラーが繰り返し発生する場合は、サポートにお問い合わせください。

• VIEWS_NOT_SUPPORTED: ビューはサポートされていません。

  Unity Catalog で 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
  ------------- ----------- ----------- -------------- ------------- ----------- -----------     ---------------------------------
  ...

関連記事

• CREATE TABLE
• CREATE VIEW
• SHOW CREATE TABLE