メインコンテンツまでスキップ

互換Mode

備考

プレビュー

この機能は パブリック プレビュー段階です。

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

概要​

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

  • Delta Lakeクライアントとの相互運用性 : Amazon Athena、Microsoft Fabric、Snowflake、 Amazon Redshiftなどのクライアントから、ストレージから直接、または Unity REST APIを通じて、 Microsoft Amazon Snowflake読み取ります。
  • Icebergクライアントとの相互運用性 : Iceberg REST カタログを通じて、 Apache Spark 、 Apache Trino、 SnowflakeなどのIcebergクライアントからストリーミング テーブルやRESTを含むIcebergテーブルを読み取ります。
  • 設定して忘れる自動化 : 互換バージョンのデータとメタデータの更新を自動化し、更新間隔をほぼ一日に設定できるようにします。

前提条件​

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

さらに、適切な設定と権限を持つ外部ロケーションがUnity Catalogに登録されていることを確認します。

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

テーブルで互換Modeを有効にする​

ストリーミング テーブル、マテリアライズドビュー、およびマネージド シャロー クローンの場合、テーブル作成時に次のテーブル プロパティを設定します。

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

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

SQL
-- 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はスキーマです。

互換Modeが有効になっているか確認する​

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

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

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

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

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

更新間隔を設定する​

Unity Catalogマネージドテーブルの場合、更新間隔を設定することで、互換Modeバージョンが更新される頻度を構成できます。

SQL
-- 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に設定した場合です。この場合、Databricks はコミットごとに変更をチェックし、必要に応じて更新をトリガーします。

ストリーミングテーブルとマテリアライズドビューの場合、更新間隔は必要ありません。 0 MINUTESはデフォルト値です。

注記

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

手動更新​

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

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

手動更新は、互換Modeが正しく動作しているかどうかをテストする場合や、次回の読み取り前に互換バージョンが最新であることを保証する場合に役立ちます。 ただし、自動更新を待つ方がコスト効率が高くなる可能性があります。

データとメタデータの生成ステータスを監視する​

互換Modeは、データとメタデータが非同期的に自動的に生成されます。 Unity Catalogマネージドテーブルの場合、生成は、余裕により、または設定された更新間隔に基づいて 1 時間ごとに行われます。 ストリーミングテーブルとマテリアライズドビューの場合、新規コミットがある場合はテーブル更新後に生成されます。

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

  1. ソース テーブルの最新バージョンを見つけるには、 DESCRIBE HISTORYを使用します。

    SQL
    DESC HISTORY my_catalog.my_schema.my_table

    最新のテーブルバージョンを確認するにはDESCRIBE HISTORY 」コマンド

    このコマンドは、 Delta Lakeバージョンとタイムスタンプを含む、互換Modeへの更新履歴を返します。 一番上の行には最新のバージョンとタイムスタンプが含まれています。

  2. 互換Modeの対応するバージョンを見つけるには、 DESCRIBE EXTENDEDを使用します。

    SQL
    DESC EXTENDED my_catalog.my_schema.my_table

    DESCRIBE EXTENDED 互換Modeバージョンを確認するコマンド

    [Uniform Compatibility Information] の下のフィールドを探します。

    • 最終更新バージョン : 互換Modeで最後に更新されたDelta Lakeバージョン
    • 最終更新日時 : 最終更新のタイムスタンプ

    テーブルのバージョンがステップ 1 で見つかったバージョンと一致する場合、互換Modeは最新です。

  3. 互換バージョン自体にDESC HISTORY使用します。

    SQL
    DESC HISTORY delta.\`<compatibility_location>\`

    最新のテーブルバージョンを確認するにはDESCRIBE HISTORY 」コマンド

  4. カタログ エクスプローラーで、互換性バージョンのメタデータ フィールドを表示します。Delta Lakeバージョンが手順 3 で見つかったバージョンと一致する場合、互換Modeは最新です。

    最新のテーブルメタデータバージョンを確認する

コストを監視する​

予測的最適化は、互換Modeの自動更新を行うコンピュート クラスターを処理します。 関連するコストを表示するには、システムの課金テーブルをクエリします。

SQL
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を使用します。

SQL
VACUUM delta.'<compatibility_mode_location_path>';

互換Mode場所のパスを見つけるには、 「互換Modeが有効になっているかどうかを確認する」のDESCRIBE EXTENDEDコマンドを使用します。 出力では、 delta.universalFormat.compatibility.locationの値が場所になります。

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

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

Amazonアテナ​

  1. Athena クエリ エディタで、指定した場所に外部テーブルを作成します。

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

  2. 表を読んでください:

    SQL
    SELECT * FROM <table_name>

Snowflake Delta Lakeリーダー​

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

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

    SQL
    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;

  3. テーブルを更新します ( SnowflakeのDelta Lake形式では自動更新はサポートされていません)。

    SQL
    ALTER EXTERNAL TABLE <table_name> REFRESH;

  4. 表を読んでください:

    SQL
    SELECT * FROM <table_name>;

Microsoftファブリック​

  1. Fabric 容量、ワークスペース、Synapse ノートブックを作成します。

  2. 互換性のある場所にデータを含むレイクハウスを作成します。

  3. ファイルを Delta Lake テーブルとして読み取ります。

    Python
    spark.read.format("delta").load("Files/<path_to_data>")

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

互換Modeが有効になっているテーブルは、特別な を使用した 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 カタログから互換性バージョンを読み取る​

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

セットアップ要件​

  1. メタストアでの外部データ アクセスを有効にします。
  2. スキーマに対するEXTERNAL USE SCHEMA権限を付与します。
  3. Databricks Personal アクセス内部 (PAT) を作成します。

Apache Spark の設定​

Bash
bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-aws-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構成​

SQL
CREATE OR REPLACE CATALOG INTEGRATION my_uc_int
  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'
    CATALOG_NAME = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<PAT>'
  )
  ENABLED = TRUE;

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

互換Modeを無効にする​

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

SQL
-- 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' = '')
警告

互換Modeの設定を解除すると、データとメタデータの生成が直ちに停止します。 7 日後、関連データとメタデータは削除されます。この 7 日間の期間内であれば、同じテーブルで互換Modeを再度有効にすることで、データとメタデータを復元できます。

制限事項​

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