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

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

`SET MANAGED` の概要

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

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

前提条件

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

外部テーブルに対するすべてのリーダーとライターは、名前ベースのアクセスを使用する必要があります。例えば：
SQL
```
SELECT * 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) をキャンセルし、外部テーブルをマネージドテーブルに変換する間はジョブをスケジュールしないでください。

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

重要

SET MANAGEDコマンドは、 Databricks Runtime 17.0 以降およびサーバレスコンピュートで使用できます。

TRUNCATE UNIFORM HISTORYコマンドは、 Databricks Runtime 17.2 以降およびサーバレスコンピュートで使用できます。

外部テーブルでApache Iceberg読み取り ( UniForm ) が有効になっているかどうかに応じて、次のコマンドのいずれかを実行して、それをUnity Catalogマネージドテーブルに変換します。テーブルで Apache Iceberg読み取り (UniForm) が有効になっているかどうかを確認するには、「Iceberg 読み取り (UniForm) が有効になっていることを確認する」を参照してください。

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として表示されます。

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

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

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

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

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

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

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

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

重要

UNSET MANAGEDコマンドは、 Databricks Runtime 17.0 以降およびサーバレスコンピュートで使用できます。

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

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

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

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

SQL
ALTER TABLE catalog.schema.my_managed_table UNSET MANAGED

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

ロールバックの確認

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

SQL
DESCRIBE EXTENDED catalog_name.schema_name.table_name

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

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

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

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

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

初期データコピー (ダウンタイムなし) : この最初のステップ中に、テーブルデータとDeltaトランザクションログが外部ロケーションから管理された場所にコピーされます。リーダとライタは外部環境でも通常どおり動作し続け、継続的な動作に影響はありません。
管理された場所に切り替える (短いダウンタイム) : この 2 番目のステップ中に、最初のステップで外部ロケーションに行ったコミットが管理された場所に移動されます。また、テーブルのメタデータが更新され、新しいマネージドテーブルの場所が登録されます。このステップの間、外部ロケーションへのすべての書き込みは一時的にブロックされ (キューに入れられず、再試行されません)、ライターのダウンタイムが発生します。 Databricks Runtime 16.1 以降のリーダーではダウンタイムは発生しませんが、Databricks Runtime 15.4 のリーダーではダウンタイムが発生する可能性があります。

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

テーブルサイズ	推奨されるクラスタリングサイズ	データ・コピーの時間	リーダーとライターのダウンタイム
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;
```

SET MANAGED の概要​

前提 条件​

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

小切手変換​

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

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

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

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

破損した外部テーブル​

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

ロールバックの確認​

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

既知の制限事項​