SYNC

  • [アーティクル]

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

SYNC コマンドは、Hive メタストアの外部テーブルを Unity Catalog の外部テーブルにアップグレードするために使用されます。 これを使用すると、既存の 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 コマンドが実行されると、 SET TBLPROPERTIES 操作によって、ターゲット Unity Catalog の外部テーブル参照を示すテーブル プロパティが追加されます。 この操作により、新しい 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 Catalog 内の既存のスキーマ。

    • source_schema

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

  • TABLE

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

    • target_table

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

    • source_table

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

  • principal

    必要に応じて、Unity Catalog のアップグレードされたテーブルの所有者を 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 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 にマネージド テーブルを作成します。

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