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

Databricksで外部テーブルをUnity Catalog管理のマネージドテーブルに変換するには、 ALTER TABLE ... SET MANAGED コマンドまたはカタログエクスプローラーを使用します。この変換処理により、ダウンタイムを最小限に抑え、テーブルの履歴、権限、ビューを保持します。

`SET MANAGED`概要

SET MANAGEDを使用して、外部テーブルをUnity Catalogマネージドテーブルに変換します。変換にはCREATE TABLE AS SELECT (CTAS) を使用することもできますが、Databricks では次の利点があるためSET MANAGED推奨しています。

リーダーとライターのダウンタイムを最小限に抑えます。
変換中にライブラリ書き込みを処理します。
テーブルの履歴を保持します。
名前、設定、権限、ビューなど、同じテーブル構成を保持します。
変換されたマネージドテーブルから外部テーブルへのロールバックをサポートします。
パスベースの読み書きをリダイレクトすることで、変換後も既存コードが機能するようにします。

前提条件

SET MANAGED、UNSET MANAGED、またはTRUNCATE UNIFORM HISTORYを使用するには、Databricks Runtime 17.3 LTS以降またはサーバレスコンピュートを使用する必要があります。
表はデルタレイク形式でなければなりません。
Databricksのソーステーブルのリーダーおよびライターは、Databricks Runtime 15.4 LTS以上を使用しなければなりません。もしリーダーやライターが14.3 LTS以下を使用している場合は、 Databricks Runtime 14.3 LTS以下のリーダーとライター向けの代替オプションをご覧ください。
外部 ( Databricks以外) クライアントは、 Unity Catalogマネージドテーブルへの読み取りをサポートする必要があります。 Deltaクライアントを使用したAccessテーブルを参照してください。
- Access Insights ダッシュボードを使用して、テーブルにアクセスするリーダーとライターがDatabricks Runtimeか外部の非Databricksかを確認します。
お使いのテーブルにminReaderVersion=2、minWriterVersion=7、およびtableFeatures={..., columnMapping}がある場合、SET MANAGEDコマンドはDELTA_TRUNCATED_TRANSACTION_LOGエラーで失敗します。お使いのテーブルにこれらのプロパティがあるかどうかをDESCRIBE DETAILを使用して確認してください。Delta Lakeの機能の互換性とプロトコルを参照してください。

変換後、パスに基づく読み取りと書き込みは、わずかなパフォーマンスオーバーヘッドを伴いながら、新しい管理対象場所に自動的にリダイレクトされます。Databricksは、パフォーマンスのオーバーヘッドを回避するため、パスベースのアクセスをすべて名前ベースのアクセスに移行することを推奨しています。パスベースのリダイレクトを参照してください。

重要

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

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

備考

ベータ版

Catalog Explorer を使用した外部からマネージドテーブルへの変換はベータ版です。

Catalog Explorer
SQL

カタログエクスプローラーを使用して変換する場合、名前ベースのアクセスが自動的に使用されます。スキーマ内の 1 つ以上の外部テーブルを一度に変換できます。

カタログエクスプローラーで、変換するテーブルまたはスキーマに移動します。
[このテーブルについて] (テーブルの詳細ページ) または [このスキーマについて] (スキーマの詳細ページ) で、 [最適化の調査] を クリックします。
Unity Catalogマネージドテーブルに移行する理由は? ダイアログで、 [続行] をクリックします。
変換する外部テーブルを選択します。テーブルの詳細ページからダイアログを開いた場合、テーブルは事前に選択されています。追加のテーブルを検索するには、検索バーを使用します。マネージドテーブルは選択できません。
[変換ノートブックを作成] をクリックします。
必要に応じて、ノートブックの名前を入力します。無事に、ノートブックがあなたのホームに保存されます。別の場所に保存するには、 「参照」 をクリックします。
ノートブックでベストプラクティスを確認し、すべての前提条件を満たしていることを確認します。
SET MANAGED クエリ セルを実行します。

セルが実行されると、カタログエクスプローラーでテーブルタイプが EXTERNAL ではなく MANAGED として表示されます。ステータスがすぐに更新されない場合は、ページを更新してください。

お使いの外部テーブルでApache Iceberg読み取り (UniForm) が有効になっているかどうかに応じて、次のいずれかのコマンドを実行します。Iceberg読み取りが有効になっていることを確認して、お使いのテーブルでApache Iceberg読み取り (UniForm) が有効になっているかを確認してください。

Apache Iceberg 読み取り (UniForm) が有効になっていない Unity Catalog 外部テーブルの場合:
SQL
```
ALTER TABLE catalog.schema.my_external_table SET MANAGED;
```
変換後は、互換性を気にせずにマネージドテーブルでIceberg読み取りを有効にすることができます。
Apache 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.3 LTS以降またはサーバレスコンピュートが必要です）。

SQL
VACUUM my_converted_table

注記

予測的最適化が有効になっている場合でも、Unity Catalogの外部ロケーションにあるデータは14日後も削除されない可能性があります。たとえば、これはマネージドテーブルがめったに使用されない場合や非常に小さい場合に発生する可能性があります。以前のデータが残っている場合は、手動でVACUUMを実行して削除してください。

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

変換を確認する

Catalog Explorer
SQL

ページを更新してください。 [詳細 ] タブの [このテーブルについて ] で、テーブルの 種類が [管理対象] として表示されます。

次のコマンドを実行して、外部テーブルがマネージドテーブルに変換されたことを確認します。

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 LTS以下のリーダーやライターがいれば、 SET MANAGED も使えます。しかし、マネージドテーブルに変換した後は、過去のコミットへのタイムトラベルはバージョン別のみで、タイムスタンプはできません。14日間のウィンドウで外部テーブルにロールバックすると、変換前に行われた過去のコミットへのタイムトラベルが再び有効になります。

いずれの場合も、タイムスタンプ付きのタイムトラベルは、変換とロールバックの間にマネージドテーブルへのコミットには機能しません。

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

SQL
ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;

パスベースのリダイレクト

備考

プレビュー

パスベースのリダイレクトはパブリックプレビュー版として提供されています。登録するには、このフォームにご記入ください。

Databricks Runtime 18.1以降では、外部テーブルをUnity Catalogマネージドテーブルに変換すると、パスベースの読み書きが自動的に新しい管理された場所へリダイレクトされます。パスベースのリダイレクトは、ストレージパスを使用するレガシーコードがリファクタリングなしで動作を続けられることで、マネージドテーブルへの移行に必要な時間と労力を削減します。

低遅延のユースケースにおいては、Databricksはパスベースのアクセスから名前ベースのアクセスへの移行を推奨します。パスベースのリダイレクトは、パスベースの読み取りまたは書き込みごとに数百ミリ秒のオーバーヘッドを追加し、 Unity Catalogで古いDeltaログがアクティブな状態を維持する必要があります。名前ベースの読み書きには、追加のパフォーマンスオーバーヘッドはありません。

ストリーミング動作

パスベースのリダイレクトを使用したストリーミングの場合：

読み取り機能は、Databricks Runtime 18.1以降でサポートされています。
書き込み機能は、Databricks Runtime 18.2以降でサポートされています。

変換後、以前のテーブル位置からの読み書きを避けるため、すべてのストリーミングジョブを再起動する必要があります。

パスベースのストリーミング読み取りと書き込みが失敗し、次のチェックポイントで移行メッセージとともに停止します。

読み取りの場合、ストリームはエラーを発生させます: DELTA_STREAMING_INTERRUPTED_BY_MANAGED_TABLE_CONVERSION: The table at <path> has been converted to a Unity Catalog managed table. The stream has been stopped to ensure data consistency. Restart the stream and it will automatically resume from the last committed offset using the converted table 。
書き込みの場合、変換後の最初のマイクロバッチでエラーが発生します: Operation not allowed: STREAMING WRITE cannot be performed on a table with redirect feature. The no redirect rules are not satisfied [] 。

エラーを解決するには、同じ設定でストリームを再起動してください。パスベースのアクセスは自動的にマネージドテーブルにリダイレクトされます。

制限事項

パスベースのリダイレクトは移行プロセスに対する下位互換性のみを持ち、Unity Catalogマネージドテーブルへの新しいパスベースのアクセスを有効にしません。

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

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

Databricks Runtime バージョンの一貫性

異なる 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などの基本操作を実行できることを確認してください。

ファイル検証失敗

SET MANAGEDコマンドは、テーブルの最新のスナップショット内のすべてのファイルがマネージドテーブルの新しい場所にコピーされていることを検証します。ファイルが不足している場合、コマンドはDELTA_ALTER_TABLE_SET_MANAGED_FAILED.FILE_VALIDATION_FAILEDエラーで失敗します。

この問題を解決するには:

Spark ドライバーログをチェックして、移行できなかったファイルを特定します。
これらのファイルがソース外部テーブルの場所に存在し、アクセス可能であることを確認します。
ALTER TABLE ... SET MANAGEDコマンドを再試行してください。

問題が解決しない場合は、Databricks サポートにお問い合わせください。

外部テーブルにロールバックする

重要

UNSET MANAGEDコマンドはサーバレスコンピュートかDatabricks Runtime 17.3 LTS以上のコンピュートが必要です。

外部テーブルをマネージドテーブルに変換した後、 UNSET MANAGED コマンドを使うことで14日以内にロールバックできます。

ロールバックすると、テーブルのメタデータが更新され、元の外部ロケーションを指すようになります。変換後にマネージドロケーションに対して行われたすべての書き込みは保持されます。変換とロールバックの間でマネージドロケーションに対して行われたコミットは、バージョンによるタイムトラベルを可能にしますが、タイムスタンプによるタイムトラベルはできません。

ロールバックの 7 日後、Databricks は管理対象の場所にあるデータを自動的に削除します。

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

SQL
ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;

ロールバックコマンドが中断された場合は、再度実行して再試行してください。

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

ロールバックを確認する

変換がロールバックされたことを確認するには、次のコマンドを実行します。

SQL
DESCRIBE EXTENDED catalog_name.schema_name.table_name

テーブルTypeはEXTERNALとして表示されます。

カタログエクスプローラーでテーブルを表示している場合は、ページを更新します。 [詳細 ] タブの [このテーブルについて] で、テーブル タイプが EXTERNALと表示されます。

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

SET MANAGEDコマンドは、 DEEP CLONEなどの代替アプローチと比較して、ダウンタイムを最小限に抑えるか、または排除します。変換プロセスでは、次の 2 段階のアプローチが使用されます。

初期データコピー (ダウンタイムなし): テーブルデータとDeltaトランザクションログが外部ロケーションから管理されたロケーションにコピーされます。リーダーとライターは、進行中の操作に影響を与えることなく、正常に動作し続けます。
管理された場所への切り替え(短いダウンタイム): 最初のステップで外部ロケーションにコミットされたものは管理された場所に移動し、テーブルのメタデータは新しい管理された場所を登録するために更新されます。このステップでは、外部ロケーションへの書き込みが一時的にブロックされ、ライターのダウンタイムが発生します。Databricks Runtime 16.4 LTS 以降の読者はダウンタイムを経験しませんが、Databricks Runtime 15.4 LTS の読者はダウンタイムを経験する可能性があります。

以下の表は、ソーステーブルのサイズに基づく推定ダウンタイムを示しています:

テーブルサイズ	推奨されるクラスタリングサイズ	データ・コピーの時間	リーダーとライターのダウンタイム
100 GB 以下	32 コア / X-Large SQLウェアハウス	約6分以内	約1～2分以内
1 TB	64 コア / 2X-Large SQLウェアハウス	~30分	約1～2分
10 TB	256 コア / 4X-Large SQLウェアハウス	~1.5時間	約1～5分

推定では、スループットレートが 0.5 ～ 2 GB/CPU コア/分であると想定されています。

注記

ダウンタイムはファイルサイズ、ファイル数、コミット数などの要因によって異なる場合があります。

制限事項

変換後、すべてのストリーミングジョブを再起動する必要があります。ストリーミング動作を参照してください。
変換後かつロールバック前に作成されたコミットのテーブル履歴は、バージョンごとにタイムトラベルは可能ですが、タイムスタンプごとのタイムトラベルはできません。
OpenSharing は SET MANAGED コマンドと完全には互換性がありません。Open OpenSharingは期待どおりに動作しますが、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のメタストア、カタログ、またはスキーマの安全に管理されている場所が、外部テーブルのストレージの場所とは異なるクラウドリージョンにある場合、クラウドプロバイダーから追加のクロスリージョンデータ転送コストが発生する可能性があります。

スキーマ、カタログ、メタストアの場所を確認するには:
SQL
```
DESC SCHEMA EXTENDED <catalog_name>.<schema_name>;

DESC CATALOG EXTENDED <catalog_name>;

SELECT * FROM system.information_schema.metastores;
```

SET MANAGED概要​

前提 条件​

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

変換を確認する​

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

パスベースのリダイレクト​

ストリーミング動作​

制限事項​

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

Databricks Runtime バージョンの一貫性​

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

破損した外部テーブル​

ファイル検証失敗​

外部テーブルにロールバックする​

ロールバックを確認する​

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

制限事項​

`SET MANAGED`概要

前提条件

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

変換を確認する

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

パスベースのリダイレクト

ストリーミング動作

制限事項

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

Databricks Runtime バージョンの一貫性

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

破損した外部テーブル

ファイル検証失敗

外部テーブルにロールバックする

ロールバックを確認する

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

制限事項