互換モード

Important

互換モードを使用すると、Azure Databricks で最適なパフォーマンスを維持しながら、Unity カタログのマネージドテーブル、具体化されたビュー、およびストリーミングテーブルを外部システムから読み取ることができます。この機能により、Delta Lake または Iceberg クライアントからアクセスできるテーブルの読み取り専用バージョンが自動的に生成されます。

概要

マネージドテーブル、ストリーミングテーブル、または具体化されたビューで有効にすると、互換モードでは、選択した場所にテーブルの読み取り専用バージョンが生成されます。この互換性バージョンには、Delta Lake 形式と Iceberg 形式の両方の v1 メタデータが含まれており、次の機能が提供されます。

Delta Lake クライアントとの相互運用性: ストリーミングテーブルや具体化されたビューを含むマネージドテーブルを、Amazon Athena、Microsoft Fabric、Snowflake、Amazon Redshift などのクライアントからストレージから直接、または Unity REST API 経由で読み取ります
Iceberg クライアントとの相互運用性: Apache Spark、Apache Trino、Snowflake などの Iceberg クライアントから Iceberg REST カタログを介して、ストリーミングテーブルや具体化されたビューを含むマネージドテーブルを読み取ります
設定と忘れの自動化: 互換性バージョンのデータとメタデータの更新を自動化し、更新間隔をほぼリアルタイムに構成する機能

[前提条件]

テーブルで互換モードを有効にするには、Unity カタログを使用している必要があります。 Unity カタログストリーミングテーブル、Unity カタログマテリアライズドビュー、Unity カタログマネージドテーブルのみがサポートされます。 Unity カタログの外部テーブルはサポートされていません。

さらに、適切な設定とアクセス許可を持つ外部の場所が Unity カタログに登録されていることを確認します。

ターゲットの場所は、ストレージアカウントに存在し、空である必要があります。
ターゲットの場所またはその親フォルダーのいずれかを Unity カタログの外部の場所として登録する必要があります。
外部の場所に対する CREATE EXTERNAL TABLE 特権が必要です。
ターゲットの場所と親フォルダーまたは子フォルダーが、過去 7 日以内に別のテーブルの互換モードの場所として使用されていない必要があります。

テーブルで互換モードを有効にする

ストリーミングテーブル、具体化されたビュー、管理された簡易クローンの場合は、テーブル作成時に次のテーブルプロパティを設定します。

CREATE [STREAMING TABLE | MATERIALIZED VIEW | TABLE] my_catalog.my_schema.my_table
TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Unity カタログのマネージドテーブルの場合のみ、既存のテーブルを変更するときに互換モードを有効にすることもできます。

-- For existing managed tables
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

互換性バージョンが初めて生成されるまでに最大 1 時間かかります。テーブルをすぐに手動で更新して、動作していることを確認できます。

注

完全な 3 部構成のテーブル名 (catalog.schema.table_name) を指定する必要があります。たとえば、 users.john.my_tableの場合、 usersはカタログであり、 john はスキーマです。

互換モードが有効になっているかどうかを確認する

テーブルで互換モードが有効になっていることを確認するには、 delta.universalFormat.enabledFormats = 'compatibility' テーブルのプロパティが存在することを確認します。このプロパティは、カタログエクスプローラー UI のテーブルの [詳細] タブで表示できます。

ノートブックで次の SQL コマンドを実行することもできます。

DESC DETAIL my_catalog.my_schema.my_table
DESC EXTENDED my_catalog.my_schema.my_table

出力で次のプロパティを探します。

delta.universalFormat.enabledFormats: "compatibility" 互換モードが有効になっていることを示します
delta.universalFormat.compatibility.location 互換モードバージョンの場所を表示します

更新間隔を構成する

Unity カタログのマネージドテーブルの場合は、更新間隔を設定することで、互換モードのバージョンを更新する頻度を構成できます。

-- Evaluate whether a refresh is needed after every commit (fastest)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '0 MINUTES'
)

-- Refresh hourly (default)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '1 HOUR'
)

既定の更新間隔は 1 HOUR。更新間隔を 1 時間未満に設定することはお勧めしません。更新が頻繁に行われることはありません。更新間隔を 0 MINUTESに設定する場合は例外です。この場合、Azure Databricks はコミットのたびに変更をチェックし、必要に応じて更新をトリガーします。

ストリーミングテーブルと具体化されたビューの場合、更新間隔は必要ありません。既定値は 0 MINUTES です。

注

更新時間に大きな影響を与える変更 (列の名前変更や型拡大の有効化など) は、ターゲットの更新間隔に関係なく 1 時間ごとに実行されます。

手動更新

互換性バージョンの更新を手動でトリガーするには:

REFRESH [TABLE | STREAMING TABLE | MATERIALIZED VIEW] my_catalog.my_schema.my_table SYNC UNIFORM

手動更新は、互換モードが正しく動作しているかをテストしたり、互換性バージョンがデータを読み込む前に最新であることを保証したりするのに役立ちます。ただし、自動更新を待機すると、コスト効率が高くなります。

データとメタデータ生成の状態を監視する

互換モードでは、データとメタデータが自動的かつ非同期的に生成されます。 Unity カタログのマネージドテーブルの場合、生成は既定で 1 時間ごと、または構成された更新間隔に基づいて行われます。ストリーミングテーブルと具体化されたビューの場合、新しいコミットがある場合、テーブルの更新後に生成が行われます。

データとメタデータが正常に生成されたかどうかを確認するには:

DESCRIBE HISTORYを使用して、ソーステーブルの最新バージョンを検索します。
```
DESC HISTORY my_catalog.my_schema.my_table
```
このコマンドは、Delta Lake のバージョンとタイムスタンプを含む、互換性モードへの更新の履歴を返します。一番上の行には、最新バージョンとタイムスタンプが含まれています。
DESCRIBE EXTENDEDを使用して、互換モードの対応するバージョンを見つけます。
```
DESC EXTENDED my_catalog.my_schema.my_table
```
互換性モードのバージョンを確認するには、DESCRIBE EXTENDED コマンドを使用します。

[Uniform Compatibility Information]\(統一互換性情報\) の下のフィールドを探します。
- 最新の更新バージョン: 互換性モードで最後に更新された Delta Lake バージョン
- 最終更新日: 最後の更新のタイムスタンプ
表のバージョンが手順 1 で見つかったバージョンと一致する場合、互換モードは最新の状態です。
互換性バージョン自体で DESC HISTORY を使用します。
```
DESC HISTORY delta.\`<compatibility_location>\`
```
カタログエクスプローラーで、互換性バージョンのメタデータフィールドを表示します。手順 3 で見つかったバージョンと Delta Lake のバージョンが一致する場合、互換モードは最新です。

コストを監視する

予測最適化は、互換性モードの自動更新を実行するコンピューティングクラスターを処理します。関連するコストを表示するには、システム請求テーブルに対してクエリを実行します。

SELECT
  DATE_TRUNC('DAY', start_time) AS day,
  SUM(usage_quantity) AS dbus
FROM
  system.storage.predictive_optimization_operations_history
WHERE
  operation_type = "COMPATIBILITY_MODE_REFRESH"
GROUP BY 1
ORDER BY 1 DESC;

このクエリでは、自動更新のみの使用状況が報告されます。手動更新のコストはコンピューティングに関連付けられます。これらのコストを個別に追跡する直接的な方法はありません。一般に、手動トリガーのコストは、元のテーブルに対する初期書き込み操作のコストに比例します。

未使用のデータファイルを削除する

互換性バージョンのテーブルで未使用のデータファイルを削除するには、次の VACUUMを使用します。

VACUUM delta.'<compatibility_mode_location_path>';

互換モードの場所のパスを見つけるには、「互換モードがDESCRIBE EXTENDEDする」のコマンドを使用します。出力では、 delta.universalFormat.compatibility.location の値は場所です。

外部クライアントから互換性バージョンを読み取る

Delta Lake または Iceberg クライアントを使用して、互換性バージョンからデータを読み取ることができます。 Amazon Athena、Snowflake (Delta Reader)、Fabric の例については、以下を参照してください。

Amazon Athena

アテナクエリエディターで、指定した場所を持つ外部テーブルを作成します。

CREATE EXTERNAL TABLE <table_name>
LOCATION '<compatibility_location>'
TBLPROPERTIES ('table_type' = 'DELTA')

テーブルを読み取る:
```
SELECT * FROM <table_name>
```

Snowflake Delta Lake 閲覧者

ストレージの場所にアクセスするためのストレージ統合を作成します ( Snowflake のドキュメントを参照)。

Delta Lake 形式の外部テーブルを作成します。

CREATE OR REPLACE EXTERNAL TABLE <table_name>
WITH LOCATION = @<my_location>
FILE_FORMAT = (TYPE = PARQUET)
TABLE_FORMAT = DELTA
AUTO_REFRESH = false
REFRESH_ON_CREATE = false;

テーブルを更新します (Snowflake の Delta Lake 形式では自動更新はサポートされていません)。
```
ALTER EXTERNAL TABLE <table_name> REFRESH;
```
テーブルを読み取る:
```
SELECT * FROM <table_name>;
```

Microsoft Fabric

ファブリック容量、ワークスペース、Synapse ノートブックを作成します。
互換性の場所にデータを含むレイクハウスを作成します。
Delta Lake テーブルとしてファイルを読み取ります。
```
spark.read.format("delta").load("Files/<path_to_data>")
```

Unity REST API から互換性バージョンを読み取る

互換モードが有効になっているテーブルは、Unity REST API を使用して特別なパラメーターを使用して名前で読み取ることができます。ストリーミングテーブルの場合は、次の API パラメーターを設定します。

GET /api/2.1/unity-catalog/tables/{full_name}?read_streaming_table_as_managed=true

具体化されたビューの場合は、次の API パラメーターを設定します。

GET /api/2.1/unity-catalog/tables/{full_name}?read_materialized_view_as_managed=true

Iceberg REST カタログから互換性バージョンを読み取る

互換モードが有効になっているテーブルは、Iceberg REST カタログを使用して任意の Iceberg クライアントから読み取ることができます。互換モードは、Delta Lake と Iceberg の両方のテーブル形式に対して自動的に機能します。

セットアップ要件

メタストアで外部データアクセスを有効にします。
スキーマにEXTERNAL USE SCHEMAの権限を付与します。
Azure Databricks 個人用アクセストークン (PAT) を作成します。

Apache Spark の構成

bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-azure-bundle:1.8.0 \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf spark.sql.catalog.catalog_name=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.catalog_name.type=rest \
  --conf spark.sql.catalog.catalog_name.uri=<workspace-url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.catalog_name.token=<PAT> \
  --conf spark.sql.catalog.catalog_name.warehouse=<uc-catalog-name>

詳細については、「 Apache Spark での Iceberg テーブルの使用」を参照してください。

Snowflake の構成

Snowflake には、Iceberg REST カタログを介して互換モードテーブルにアクセスするための 2 つのオプションが用意されています。Snowflake のカタログにリンクされたデータベースを使用するか、外部テーブルを使用します。

どちらのオプションでも、最初に Snowflake カタログ統合を構成します。

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

次の変数を置換してください。

<catalog-integration-name>: Snowflake に登録されているカタログを割り当てる名前。
<uc-schema-name>: アクセスする必要がある Unity Catalog 内のスキーマの名前。
<uc-catalog-name>: アクセスする必要がある Unity Catalog 内のカタログの名前。
<workspace-url>: Azure Databricks ワークスペースの URL。
<token>: 統合の設定に使用する管理者の PAT トークン。

カタログにリンクされたデータベース

Snowflake のカタログにリンクされたデータベースは、Unity カタログと自動的に同期され、スキーマと Iceberg テーブルが検出されます。これにより、メタデータの手動更新が不要になります。

Snowflake カタログ統合を構成した後、 Snowflake のドキュメントを参照して、テーブルにアクセスするためのカタログリンクデータベースを作成します。

注

互換モードでアクセスされるテーブルは読み取り専用です。カタログにリンクされたデータベースは Snowflake 機能であるため、Databricks では、互換性モードが有効になっている Azure Databricks ストリーミングテーブル、具体化されたビュー、またはマネージドテーブルでサポートされている操作について Snowflake ドキュメントを参照することをお勧めします。

外部テーブル

または、Snowflake カタログ統合の作成後に外部テーブルを作成することもできます。この方法では、更新を表示するためにメタデータを手動で更新する必要があります。

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-st/mv-name>';

互換モードを無効にする

互換モードを無効にするには、対応するテーブルプロパティの設定を解除します。

-- For UC managed tables
ALTER TABLE my_table UNSET TBLPROPERTIES('delta.universalFormat.enabledFormats')

-- For streaming tables and materialized views
CREATE OR REPLACE [STREAMING TABLE | MATERIALIZED VIEW] my_table
TBLPROPERTIES('delta.universalFormat.enabledFormats' = '')

Warnung

互換性モードの設定を解除すると、データとメタデータの生成が直ちに停止します。 7 日後、関連付けられているデータとメタデータが削除されます。この 7 日間以内に、同じテーブルで互換モードを再度有効にすることで、データとメタデータを復元できます。

制限事項

読み取り専用アクセス: 互換性バージョンは読み取り専用です。互換性バージョンに書き込むことはできません。
RLS/CLS のサポートなし: Row-Level セキュリティ (RLS) または Column-Level セキュリティ (CLS) のテーブルで互換モードを有効にすることはできません。
パーティション列の名前変更なし: 互換モードが有効になっているテーブルでは、パーティション列の名前変更はサポートされていません。データ列の名前変更がサポートされています。
制限付きテーブル機能: 互換性バージョンでは、次の機能を使用できません。
- 照合順序列
- 主キー
- タイムトラベル
- データフィードの変更
- 特殊文字を含む列名 (名前が変更されます)

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-02-21