外部テーブルをマネージド Unity Catalog テーブルに変換する
このページでは、 ALTER TABLE ... SET MANAGEDコマンドまたはカタログ エクスプローラーを使用して、 Databricksで外部テーブルをUnity Catalogマネージドテーブルに変換する方法について説明します。
SET MANAGED概要
SET MANAGEDを使用して、外部テーブルをUnity Catalogマネージドテーブルに変換します。 変換にはCREATE TABLE AS SELECT (CTAS) を使用することもできますが、Databricks では次の利点があるためSET MANAGED推奨しています。
- リーダーとライターのダウンタイムを最小限に抑えます。
- 変換中にライブラリ書き込みを処理します。
- テーブルの履歴を保持します。
- 名前、設定、権限、ビューなど、同じテーブル構成を保持します。
- 変換されたマネージドテーブルから外部テーブルへのロールバックをサポートします。
前提 条件
-
外部テーブルに対するすべてのリーダーとライターは、名前ベースのアクセスを使用する必要があります。例えば：
SQLSELECT * FROM catalog_name.schema_name.table_name;パスベースのアクセスはサポートされていないため、Databricks Runtime または OSS クライアントのバージョンによっては、データの破損や損失が発生する可能性があります。
-
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かを確認します。
競合を回避するには、テーブルで操作されている既存の 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 外部テーブルの場合:
SQLALTER TABLE catalog.schema.my_external_table SET MANAGED;変換後は、互換性を気にせずにマネージドテーブルでIceberg読み取りを有効にすることができます。
-
Apache Iceberg 読み取り (UniForm) がすでに有効になっている Unity Catalog 外部テーブルの場合:
SQLALTER TABLE catalog.schema.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;最適なテーブルのパフォーマンスと互換性を維持するには、
TRUNCATE UNIFORM HISTORYを含めます。TRUNCATE UNIFORM HISTORYUniForm Iceberg 履歴のみを切り捨て、Delta 履歴は削除しません。このコマンドを実行すると、切り捨て後に Iceberg の読み取りと書き込みのダウンタイムが短くなります。
データのコピー中にコマンドが中断された場合は、コマンドを再開すると、中断したところから続行されます。
Databricks では、テーブルの状態が不整合になる可能性があるため、同じテーブルで複数のSET MANAGEDコマンドを同時に実行しないようにすることをお勧めします。
テーブル変換後、次の操作を行う必要があります。
- 以前の場所からの読み取りや以前の場所への書き込みを回避するには、外部テーブルを使用してストリーミング ジョブ (読み取りまたは書き込み) を再起動します。現在のジョブを停止し、同じ構成で新しいジョブを開始します。
- リーダーとライターがマネージドテーブルで動作することを確認します。
予測的最適化は、手動で無効にしない限り、変換後に自動的に有効になります。 「 予測的最適化が有効かどうかを確認する 」を参照してください。
予測的最適化を有効にすると、 Databricks 14 日後にUnity Catalog外部位置のデータを自動的に削除します。 予測的最適化が無効になっている場合は、14 日後に新しく変換されたマネージド テーブルで実行VACUUM ( Databricks Runtime 17.0 以降またはサーバーレス コンピュートが必要) が実行されます。
VACUUM my_converted_table
場合によっては、予測的最適化が有効になっている場合でも、 Unity Catalog外部位置のデータが 14 日経過しても削除されないことがあります。たとえば、マネージドテーブルが頻繁に使用されていないか、非常に小さい場合です。 このような場合は、14 日後にVACUUM手動で実行して、以前のデータを削除してください。
Databricks外部ロケーションのデータのみを削除します。 Delta トランザクション ログと Unity Catalog 内のテーブルへの参照が保持されます。
変換を確認する
- Catalog Explorer
- 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 機能を削除する必要があります。
ALTER TABLE <table_name> DROP FEATURE inCommitTimestamp;
変換失敗のトラブルシューティング
このセクションでは、外部テーブルを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 は管理対象の場所にあるデータを自動的に削除します。
外部テーブルにロールバックするには、次のコマンドを実行します。
ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED;
ロールバック コマンドが中断された場合は、再度実行して再試行してください。
変換の場合と同様に、ロールバック後にストリーミング ジョブを再起動する必要もあります。
ロールバックを確認する
変換がロールバックされたことを確認するには、次のコマンドを実行します。
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コマンドはDelta Sharingと完全には互換性がありません。 Open Delta Sharing期待どおりに機能しますが、 Databricks-to-Databricks共有では受信者テーブルの管理場所が自動的に更新されません。 テーブルが再共有されるまで、受信者は古い場所から読み取りを続けます。テーブルを再度共有するには:SQLALTER SHARE <share_name> REMOVE TABLE <table_name>;
ALTER SHARE <share_name> ADD TABLE <table_name> AS <table_share_name> WITH HISTORY; -
複数のクラウド リージョン: Unity Catalog メタストア、カタログ、またはスキーマのデフォルトの管理場所が、外部テーブルのストレージ場所とは異なるクラウド リージョンにある場合、リージョン間のデータ転送コストが追加される可能性があります。クラウド プロバイダーは、Databricks の管理外でこれらの料金を課します。
スキーマ、カタログ、メタストアの場所を確認するには:
SQLDESC SCHEMA EXTENDED <catalog_name>.<schema_name>;
DESC CATALOG EXTENDED <catalog_name>;
SELECT * FROM system.information_schema.metastores;