`SYNC`

対象: 「はい」チェックマークがオン Databricks SQL Databricks Runtime Unity Catalog のみ

SYNC コマンドは、Hive メタストアに存在する外部テーブルを Unity Catalog 外部テーブルへアップグレードするために使用します。また、Databricks ワークスペースストレージ (DBFS ルートとも呼ばれる) の外部に保存されている Hive マネージドテーブルを Unity Catalog 外部テーブルにアップグレードするためにも、SYNC を使用できます。ワークスペースストレージ内に保存されている 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 以上では、spark.databricks.sync.command.disableSourceTableWrites コマンドの実行前に Spark 構成 true を SYNC に設定することで、この書き込み動作を無効にできます。 true に設定すると、SYNC は新しいテーブルプロパティを追加せず、そのためテーブルが以前に Unity Catalog にアップグレードされているかどうかを検出できない可能性があります。その場合、テーブルが以前に Unity Catalog にアップグレードされているかどうかをテーブル名のみで判定します。最後の SYNC コマンド以降にソーステーブルの名前が変更されている場合、ユーザーは、構成が SYNCされたときに true コマンドを再実行する前に、コピー先テーブルの名前を手動で変更する必要があります。

重要

SYNC コマンドの実行時には、SET TBLPROPERTIES 操作によって、ターゲットとなる Unity Catalog 外部テーブルの参照情報を示すテーブルプロパティが追加されます。この操作は新しい 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 します。
- ターゲットスキーマ
  
  ユーザーがテーブルの作成を許可されている Unity Catalog 内の既存のスキーマ。
- ソース_スキーマ
  
  ユーザーが所有する hive_metastore カタログ内の既存のスキーマ。
TABLE

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

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

Databricks ワークスペースストレージ (DBFS ルートとも呼ばれる) の外部に保存されている Hive マネージドテーブルまたはスキーマを Unity Catalog 外部テーブルに同期するために、SYNC を使用できます。ワークスペースストレージ内に保存されている Hive マネージドテーブルのアップグレードには、AS EXTERNAL を使用できません。
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 ファイルシステムのルートにあるテーブル。

テーブルは Databricks ファイルシステムのルートの場所にあります。これは、Unity Catalog ではサポートされていません。 CREATE TABLE コマンドと DEEP CLONE オプションを使用して、テーブルデータを Unity カタログの場所にコピーします。
EXTERNAL_TABLE_IN_MANAGED_LOCATION: 外部テーブルパスをマネージドストレージの下に置くことはできません。

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

Hive SerDe テーブルは Unity Catalog ではサポートされていません。テーブルを Delta 形式に変更し、SYNC コマンドを発行してアップグレードします。
INVALID_DATASOURCE_FORMAT: データソース形式が指定されていないか、サポートされていません。

サポートされているデータソース形式 (Delta、Parquet、CSV、JSON、ORC、TEXT、AVRO) のいずれかを使用する
LOCATION_OVERLAP: 入力パスが他の外部テーブルと重複しています。

テーブルの場所が、他の外部テーブルと重複しています。テーブルに別の場所を使用するか、重複する外部テーブルを削除します。
MULTIPLE_EXT_LOCATIONS: 入力パスに他の外部ロケーションが含まれています。

指定されたテーブルパスのサブディレクトリである複数の外部の場所があります。テーブルの場所内の外部の場所が必要かどうかを確認します。
MULTIPLE_TARGET_TABLE: 別の同期テーブルが既に存在します。ソーステーブルごとに許可されるターゲットテーブルは 1 つだけです。

ソーステーブルは、別のターゲットテーブルに既に同期されています。これは許可されません。 SYNC を別のテーブルに強制するには、ソーステーブルから table プロパティ upgraded_to を削除するか、以前に同期したテーブルが不要になった場合は Unity Catalog から削除します。
NOT_EXTERNAL: テーブルは、Hive メタストアから Unity Catalog へのアップグレードの対象ではありません。理由: 外部テーブルではありません。

SYNC コマンドでは、Unity Catalog への外部テーブルの移行のみがサポートされます。マネージドテーブルの場合は、CREATE TABLE オプションを指定して DEEP CLONE コマンドを使用して Unity カタログにマネージドテーブルを作成します。また、AS EXTERNAL 句を SYNC コマンドで使用して、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 カタログの SHOW CREATE TABLE コマンドを使用して、それらを Unity カタログに再作成します。
TIMEOUT: 同期タスクがタイムアウトしました。

同期テーブルコマンドタスクの完了に 600 秒以上かかりました。 spark.databricks.sync.command.task.timeout をもっと大きな値 (秒単位) に増やします。

または、同期スキーマタスクがタイムアウトになる場合があります。その場合は、 TimeoutExceptionが表示されます。 spark.databricks.sync.command.task.create.timeout をもっと大きな値 (秒単位) に増やします。

両方のフラグの既定値は 600 です。問題が解決しない場合は、サポートにお問い合わせください。
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
  ------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
  ...

トラブルシューティング

テーブルコメント内の ASCII 以外の文字が正しく同期されない

SYNC コマンドを使用して Hive メタストアから Unity Catalog にテーブルをアップグレードすると、ASCII 以外の文字 (日本語や中国語のテキストなど) を含むテーブルコメントが破損している可能性があります。たとえば、影響を受けるコメントが一連の疑問符 (???) として表示されたり、カタログエクスプローラーでレンダリングに失敗したりする場合があります。ただし、 DESCRIBE TABLE EXTENDED を使用してコメントに対してクエリを実行すると、正しい値が返されます。

この問題は、Hive メタストアが既定で latin1 文字セットを使用してコメントを格納する場合があり、ASCII 以外の文字をサポートしていないために発生します。 Unity カタログが SYNCを使用してコメントを取得すると、サポートされていない文字が失われたり破損したりする可能性があります。

SYNCを使用してアップグレードした後にコメント内の ASCII 以外の文字を回復または復元するには、Unity カタログの影響を受けるテーブルで次のコマンドを実行します。
```
MSCK REPAIR TABLE <catalog>.<schema>.<table_name> SYNC METADATA;
```

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-07-21

次の方法で共有

SYNC

構文

パラメーター

戻り値

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

例

トラブルシューティング

関連記事

フィードバック

その他のリソース

`SYNC`

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