外部Deltaテーブルを管理対象のUnity Catalogテーブルに変換する

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

`SET MANAGED`概要

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

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

前提条件

SET MANAGEDまたはUNSET MANAGEDを使用するには、 Databricks Runtime 17.0 以降またはサーバレスコンピュートを使用する必要があります。
表はDelta形式でなければなりません。
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テーブルを参照してください。
- Access Insights ダッシュボードを使用して、テーブルにアクセスするリーダーとライターがDatabricks Runtimeか外部の非Databricksかを確認します。

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

重要

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

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

備考

ベータ版

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

Catalog Explorer
SQL

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

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

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

外部テーブルで Apache Iceberg 読み取り ( UniForm ) が有効になっているかどうかに応じて、次のいずれかのコマンドを実行します。テーブルで Apache Iceberg読み取り (UniForm) が有効になっているかどうかを確認するには、「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.0 以降またはサーバーレスコンピュートが必要) が実行されます。

SQL
VACUUM my_converted_table

注記

場合によっては、予測的最適化が有効になっている場合でも、 Unity Catalog外部位置のデータが 14 日経過しても削除されないことがあります。たとえば、マネージドテーブルが頻繁に使用されていないか、非常に小さい場合です。このような場合は、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 以下にリーダーまたはライターがある場合は、引き続きSET MANAGED使用できます。ただし、マネージドテーブルに変換した後は、タイムスタンプによる過去のコミットへのタイムトラベルはできなくなります。バージョンのみによるものになります。 14 日間の期間内に外部テーブルにロールバックすると、変換前に行われた履歴コミットへのタイムトラベルが再度有効になります。

どのような場合でも、タイムスタンプによるUnity Catalog外部テーブルへのロールバックは、変換からロールバックまでの間に変換されたUnity Catalogマネージドテーブルに対して行われたコミットに対しては機能しません。

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.0 以降、またはサーバレスコンピュートが必要です。

外部テーブルをマネージドテーブルに変換した後、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.1 以降のリーダーではダウンタイムは発生しませんが、Databricks Runtime 15.4 のリーダーではダウンタイムが発生する可能性があります。

推定ダウンタイム:

テーブルサイズ	推奨されるクラスタリングサイズ	データ・コピーの時間	リーダーとライターのダウンタイム
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 コア/分であると想定されています。

注記

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

制限事項

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

スキーマ、カタログ、メタストアの場所を確認するには:
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 バージョンの一貫性

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

破損した外部テーブル

ファイル検証失敗

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

ロールバックを確認する

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

制限事項