メインコンテンツまでスキップ

外部テーブルをマネージド Unity Catalog テーブルに変換する

このページでは、ALTER TABLE ... SET MANAGED コマンドを使用して、Databricksで外部テーブルをUnity Catalog マネージドテーブルに変換する方法について説明します。

SET MANAGED の概要​

SET MANAGED機能を使用して、外部テーブルをDatabricksのUnity Catalogマネージドテーブルに変換します。 SET MANAGEDには次の利点があります:

  • リーダーとライターのダウンタイムを最小限に抑えます。
  • 変換中の並列書き込みの処理。
  • テーブル履歴の保持。
  • 同じテーブル構成 (同じ名前、設定、アクセス許可、ビューなど) を保持します。
  • 変換されたマネージドテーブルを外部テーブルにロールバックする機能。

前提 条件​

テーブル変換機能を使用するには、次の前提条件を満たす必要があります。

  • 外部テーブルに対するすべてのリーダーとライターは、名前ベースのアクセスを使用する必要があります。例えば：

    SQL
    SELECT * FROM catalog_name.schema_name.table_name;

    パスベースのアクセスはサポートされておらず、テーブルが変換された後で失敗します。例えば：

    SQL
    SELECT * FROM delta.`protocol://path/to/table`;

  • SET MANAGEDまたはUNSET MANAGEDを使用するには、Databricks Runtime 17.0 以上を使用する必要があります。

  • Iceberg 読み取り (UniForm) が既に有効になっている Unity Catalog テーブルを変換するには、Databricks Runtime 17.2 以上を使用してTRUNCATE UNIFORM HISTORY使用する必要があります。

  • Databricks のリーダーとライターは、Databricks Runtime 15.4 LTS 以降を使用する必要があります。リーダーまたはライターが 14.3 LTS 以下を使用している場合は、「 Databricks Runtime 14.3 LTS 以前のリーダーとライターの代替オプション」を参照してください。

  • テーブルにminReaderVersion=2 、 minWriterVersion=7 、 tableFeatures={..., columnMapping}がある場合、 SET MANAGEDコマンドはDELTA_TRUNCATED_TRANSACTION_LOGエラーで失敗します。DESCRIBE DETAILを使用して、テーブルにこれらのプロパティがあるかどうかを確認できます。

  • 外部 (非Databricks) クライアントは、 Unity Catalog マネージドテーブルへの読み取りをサポートする必要があります。 Delta クライアントを使用したテーブルの読み取りを参照してください。

    • Access Insights ダッシュボードを使用して、テーブルにアクセスするリーダーとライターがDatabricks Runtimeか外部の非Databricksかを確認します。
important

競合を回避するには、テーブルで操作されている既存の OPTIMIZE コマンドジョブ (リキッドクラスタリング、コンパクション、 ZORDER) をキャンセルし、外部テーブルをマネージドテーブルに変換する間はジョブをスケジュールしないでください。

外部テーブル からマネージドテーブルへの変換​

important

SET MANAGED コマンドは、Databricks Runtime 17.0 以降で使用できます。

TRUNCATE UNIFORM HISTORYコマンドは、Databricks Runtime 17.2 以降で使用できます。

次のコマンドのいずれかを実行して、 Unity Catalog外部テーブルをUnity Catalogマネージドテーブルに変換します。

  • Apache Iceberg 読み取り (UniForm) が有効になっていない Unity Catalog 外部テーブルの場合:

    SQL
    ALTER TABLE catalog.schema.my_external_table SET MANAGED;

    変換後は、互換性を気にせずにマネージドテーブルでIceberg読み取りを有効にすることができます。

  • Iceberg 読み取り (UniForm) がすでに有効になっている Unity Catalog 外部テーブルの場合:

    SQL
    ALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;

    この場合、最適なテーブルのパフォーマンスと互換性を維持するためにTRUNCATE UNIFORM HISTORYを含めます。TRUNCATE UNIFORM HISTORY UniForm Iceberg 履歴のみを切り捨て、Delta 履歴は削除しません。このコマンドを実行すると、切り捨て後に Iceberg の読み取りと書き込みのダウンタイムが短くなります。

データのコピー中にコマンドが中断された場合は、コマンドを再開でき、中断したところから続行されます。

警告

Databricks では、同じテーブルで複数の SET MANAGED コマンドを同時に実行しないことをお勧めします。これにより、テーブルの状態に一貫性がなくなる可能性があります。

テーブル変換後、次の操作を行う必要があります。

  • 外部テーブルを使用して、すべてのストリーミングジョブ (読み取りまたは書き込み) を再起動します。
  • リーダーとライターがマネージドテーブルで作業していることを確認します。

予測的最適化は、手動で無効にした場合を除き、自動的に有効になります。 「予測的最適化が有効かどうかを確認する」を参照してください。

予測的最適化を有効にすると、 Databricks 14 日後にUnity Catalog外部位置のデータを自動的に削除します。 予測的最適化が無効になっている場合は、14 日が経過すると、新しく変換されたマネージド テーブルで実行VACUUM ( Databricks Runtime 17.0 以降が必要) を実行できます。

VACUUM my_converted_table
注記

場合によっては、予測的最適化が有効になっている場合でも、 Unity Catalog外部位置のデータが 14 日経過しても削除されない場合があります。 たとえば、 Unity Catalogマネージドテーブルが頻繁に使用されない場合、または非常に小さい場合は、自動削除が行われない可能性があります。 このような場合は、14 日後に、新しく変換されたマネージドテーブルに対して手動で実行VACUUM ( Databricks Runtime 17.0 以降が必要) を実行して、古いデータを削除します。

Databricks外部ロケーションのデータのみを削除します。 Delta トランザクション ログと Unity Catalog 内のテーブルへの参照が保持されます。

小切手変換​

外部テーブルがマネージドテーブルに変換されたことを確認できます。

SQL
DESCRIBE EXTENDED catalog_name.schema_name.table_name

このコマンドの出力をチェックして、テーブルが変換されたことを確認します。テーブルType MANAGEDとして表示されます。

Databricks Runtime 14.3 LTS 以前のリーダーとライターの代替オプション​

Databricks では、テーブル履歴を保持する機能など、 SET MANAGED コマンドを利用するために、すべてのリーダーとライターを Databricks Runtime 15.4 LTS 以降にアップグレードすることをお勧めします。

Databricks Runtime 14.3 以前のリーダーまたはライターがいる場合でも、 SET MANAGED コマンドを引き続き使用できます。ただし、マネージドテーブルに変換した後は、タイムスタンプで過去のコミットにタイムトラベルすることはできません。これはバージョンごとにのみ実行できます。14 日間のウィンドウで外部テーブルにロールバックすると、変換前に行われた過去のコミットへのタイムトラベルが再度有効になります。

すべての場合(DBRバージョンに関係なく)、タイムスタンプによるUC外部へのロールバックは、変換が完了してからロールバックを試みる前までの間に、変換されたUCマネージドテーブルに対して行われたコミットに対しては機能しません。

Databricks Runtime 15.4 LTS 以下での変換後にテーブルに書き込むには、 inCommitTimestamp 機能を削除する必要があります。

SQL
ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

変換失敗のトラブルシューティング​

このセクションでは、外部テーブルをUnity Catalogマネージドテーブルに変換する際の一般的な問題とその解決方法について説明します。

DBRバージョンの一貫性​

異なる Databricks Runtime バージョンを使用して同じテーブルの変換を実行したり再試行したりしないでください。メタデータはバージョン間で異なる方法でシリアル化される可能性があり、その結果、 VERSIONED_CLONE_INTERNAL_ERROR.EXISTING_FILE_VALIDATION_FAILEDエラーが発生します。変換が失敗した場合は、常に同じ Databricks Runtime バージョンを使用して再試行してください。

変換中のクラスターのシャットダウン​

変換中にクラスターがシャットダウンした場合、コマンドはDELTA_ALTER_TABLE_SET_MANAGED_INTERNAL_ERRORで失敗する可能性があります。変換を再開するにはコマンドを再試行してください。

破損した外部テーブル​

外部テーブルがすでに破損している場合 (たとえば、テーブルの状態が無効)、変換はDELTA_TRUNCATED_TRANSACTION_LOG 、 DELTA_TXN_LOG_FAILED_INTEGRITY 、 DELTA_STATE_RECOVER_ERRORSなどのエラーで失敗する可能性があります。変換を試みる前に、外部テーブルに対してDESCRIBE DETAILなどの基本操作を実行できることを確認してください。

外部テーブルへのロールバック​

important

UNSET MANAGED コマンドは、Databricks Runtime 17.0 以降で使用できます。

外部テーブルをマネージドテーブルに変換した後、14 日以内であればロールバックできます。

ロールバックする場合、変換とロールバックの間に外部ロケーションに対して行われたコミットは、バージョンごとにタイムトラベル可能ですが、タイムスタンプではタイムトラベルできません。 ロールバックの 7 日後、管理された場所のデータは削除されます。

外部テーブルにロールバックするには、次のコマンドを実行します。

SQL
ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED

ロールバック・コマンドが中断された場合は、SET MANAGED コマンドと同様に、ロールバック・コマンドを再実行して再試行できます。

ロールバックの確認​

コンバージョンがロールバックされたことを確認できます。

SQL
DESCRIBE EXTENDED catalog_name.schema_name.table_name

このコマンドの出力をチェックして、テーブルがロールバックされたことを確認します。テーブルType EXTERNALとして表示されます。

また、変換と同様に、外部テーブルにロールバックした後でストリーミングジョブを再起動する必要もあります。

ダウンタイムとデータコピー時間​

変換中にリーダーまたはライターがテーブルにアクセスすると、ダウンタイムが発生する可能性があります。ただし、「ディープクローン」コマンドと比較して、 SET MANAGED コマンドは読者とライターのダウンタイムを最小限に抑えるか、排除します。 Databricks Runtime 16.1 以降の読者では、ダウンタイムは発生しません。リーダーとライターは、表データと差分ログがコピーされる最初のステップでは影響を受けません。

2 番目の手順では、 Unity Catalog 外部ロケーションへの書き込みがブロックされ、最初のデータ コピー中に外部ロケーションに対して行われたコミットは移動されます。 この 2 番目のデータ コピー手順では、Databricks Runtime 15.4 LTS 以前のライターとリーダーにダウンタイムが発生します。

この後、リーダーとライターは Unity Catalog 管理場所に移動し、新しいマネージドテーブルの場所が Unity Catalogに登録されます。 Databricks Runtime 16.1 以降を使用しているリーダーは、ダウンタイムが発生しないのと同等のエクスペリエンスが発生します。

推定ダウンタイムは次のとおりです。

テーブルサイズ

推奨されるクラスタリング サイズ

データ・コピーの時間

リーダーとライターのダウンタイム

100 GB 以下

32 コア / DBSQL スモール

~6分以内

~1-2分以下

1 TB

64 コア / DBSQL ミディアム

~30分

~1-2分

10 TB

256 コア / DBSQL x-Large

~1.5時間

~1-5分

この推定値は、0.5 から 2 GB/CPU コア/分のスループット レートを前提としています。

注記

ダウンタイムはさまざまです。変換のパフォーマンスは、ファイル サイズ、ファイル数、コミット数などの要因によって異なります。

既知の制限事項​

外部テーブル からマネージドテーブルへの変換には、次の制限があります。

  • ストリーミングクライアント : 変換後、ストリーミングジョブを再起動する必要があります。

  • ロールバック後のテーブル履歴の制約 : Databricks Runtime 15.4 LTS 以降のリーダー/ライターの場合、変換後でロールバック前に行われたコミットのテーブル履歴は、バージョンごとにタイムトラベルできますが、タイムスタンプではタイムトラベルできません。

  • Delta Sharing制限 : SET MANAGEDコマンドはDelta Sharingと完全には互換性がありません。 オープンDelta Sharing期待どおりに機能しますが、 Databricks-to-Databricks共有では受信者テーブルの管理場所が自動的に更新されません。 テーブルが再共有されるまで、受信者は古い場所から読み取りを続けます。テーブルを再度共有するには:

    SQL
    ALTER SHARE <share_name> REMOVE TABLE <table_name>;
    ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY;

  • 複数のクラウド リージョン : Unity Catalog メタストア、カタログ、またはスキーマのデフォルトの管理場所が、変換される外部テーブルのストレージ場所とは異なるクラウド リージョンにある場合、リージョン間のデータ転送コストが追加される可能性があります。クラウド プロバイダーは、Databricks の管理外でこれらの料金を課します。

    スキーマ、カタログ、およびメタストアの場所を確認するには、次のコマンドを使用します。

    SQL
    DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

    DESC CATALOG EXTENDED <catalog_name>;

    SELECT * FROM system.information_schema.metastores;
に最終更新