ストリーミングテーブルとマテリアライズドビューへの外部データアクセスを有効にする

Unity Catalog への外部データ アクセスを有効にしている場合は、パイプライン管理対象およびスタンドアロンのマテリアライズドビューとストリーミングテーブルに外部データ アクセスを追加できます。これにより、外部の Delta および Iceberg クライアントは、データの完全なコピーを必要とせずに、Unity Catalog および Iceberg カタログ REST APIs を通じてデータセットにアクセスできるようになります。

外部データアクセスは、Lakeflow Pipelines によって管理されるデータセット、およびスタンドアロンのマテリアライズドビューとストリーミングテーブルで機能します。

機能

外部データ アクセスを使用すると、データの複製を作成することなく、パイプライン管理対象およびスタンドアロンのマテリアライズドビューとストリーミングテーブルに対して、Databricks で利用可能なものと同じデータが公開されます。これにより、パフォーマンスと機能に関して次の特性が得られます。

• データコピーは不要です： 完全なデータセットを複製することなく、外部アクセスが有効になります。
• 外部アクセス（APIs経由）： Delta Lake または Iceberg の APIs を使用して、マテリアライズドビューとストリーミングテーブルを読み取ります。
• 書き込み後読み取り整合性: 外部リーダーは、データセットの更新後に最新のデータにアクセスでき、データの陳腐化がないことを保証します。更新すると、すぐに反映されます。
• 「 単一テーブルオブジェクト: 」データセットは、Unity Catalog APIs内で、ソースデータセットと同じ名前の マネージドテーブル として外部に表示されます。
• 低コスト: データセット全体がコピーされないため、外部アクセスを提供するオーバーヘッドは低くなります。

要件

データセットの要件は以下のとおりです：

• Unity Catalog： ストリーミングテーブルとマテリアライズドビューは、Unity Catalogを使用している必要があります。
• Databricks Runtime バージョン： Databricks Runtime 17.3 以降を使用する必要があります。
• default publishing mode: 外部読み取り機能は、default publishing modeでのみサポートされています。外部読み取り機能を使用するには、default公開モードに移行してください。マテリアライズドビューのチェンジデータフィードなど、外部メタデータに依存する機能は、レガシー公開モードで動作します。

クライアントの要件は次のとおりです：

• Delta API version： クライアントは、削除ベクトルを含むDelta Lake APIs 4.0.0 以降をサポートする必要があり、アクセスにはUnity CatalogカタログAPIsを使用する必要があります。
• Iceberg API バージョン： または、クライアントは、 Iceberg v3 仕様 をサポートするIceberg カタログ APIs を使用してアクセスできます。
• Unity Catalog の権限: 外部からデータセットを読み取るプリンシパルには、スキーマに対する EXTERNAL USE SCHEMA 特権、およびテーブルに対する SELECT 特権が必要です。

注記

お使いのクライアントがこれらの要件をサポートしていない場合、すべてのDeltaおよびIcebergクライアントをサポートしますが、データセットの完全なコピーを作成する必要がある互換モードを使用することもできます。

データセットへのアクセスを有効にする方法

データセットの外部アクセスを有効にするには、2 つのステップがあります。

1. パイプライン構成またはテーブルプロパティのいずれかを使用して、外部メタデータを有効にします。テーブルレベルの設定は、両方が設定されている場合にパイプライン構成よりも優先され、パイプライン管理型およびスタンドアロン型のストリーミングテーブルとマテリアライズドビューの両方でサポートされています。

   • パイプライン構成： パイプライン内のすべてのデータセットに対して外部メタデータを有効にするには、pipelines.externalMetadata.enabled を true に設定します。Databricks SQL で作成されたスタンドアロンのマテリアライズドビューとストリーミングテーブルにはパイプライン構成がないため、代わりにテーブルプロパティを使用してください。

Pipeline settings UI

In the pipeline settings, complete the following steps:

1. Open your pipeline and click Settings.
2. Under Configuration, add a key-value pair: Key pipelines.externalMetadata.enabled, Value true.
3. Click Save.

Pipeline configuration JSON

In the configuration section of your pipeline JSON, add:

JSON

{
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

• テーブルプロパティ： ストリーミングテーブルまたはマテリアライズドビューの定義に、次のプロパティを追加します。Lakeflow Connect パイプラインについては、「Delta テーブルのプロパティを設定する」を参照してください。

  SQL

  CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
  TBLPROPERTIES('pipelines.externalMetadata.enabled' = 'true')

設定を保存した後、変更を適用するには、パイプラインを実行または再起動してください。

• 「トリガーされたパイプライン」：パイプラインを一度実行します。
• 継続的パイプライン ：パイプラインを停止し、再起動します。

スタンドアロンの Databricks SQL オブジェクトの場合は、テーブルプロパティと共に CREATE OR REPLACE MATERIALIZED VIEW または CREATE OR REFRESH STREAMING TABLE を使用します。作成または更新ステートメントがプロパティを適用します。

2. 最新の Iceberg クライアントでデータセットを読み取る予定がある場合は、外部メタデータ プロパティに加えて、次の UniForm Iceberg V3 プロパティを追加してください。Lakeflow Connect パイプラインについては、Delta テーブル プロパティの設定を参照してください。

属性	使用
'pipelines.externalMetadata.enabled' = 'true'	テーブルの外部アクセスを有効にします。両方が設定されている場合、このテーブルレベルの設定がパイプライン構成よりも優先されます。
'delta.columnMapping.mode' = 'name'	Iceberg には列マッピングが必要です。
'delta.enableRowTracking' = 'true'	Iceberg 読み取りのために行追跡を有効にします。
'delta.universalFormat.enabledFormats' = 'iceberg'	Iceberg 読み取りを有効にします。
'delta.enableIcebergCompatV3' = 'true'	Iceberg 読み取りには Iceberg V3 を使用します。

属性	使用
'pipelines.externalMetadata.enabled' = 'true'	テーブルの外部アクセスを有効にします。両方が設定されている場合、このテーブルレベルの設定がパイプライン構成よりも優先されます。
'delta.columnMapping.mode' = 'name'	Iceberg には列マッピングが必要です。
'delta.enableRowTracking' = 'true'	Iceberg 読み取りのために行追跡を有効にします。
'delta.universalFormat.enabledFormats' = 'iceberg'	Iceberg 読み取りを有効にします。
'delta.enableIcebergCompatV3' = 'true'	Iceberg 読み取りには Iceberg V3 を使用します。

SQL

CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableRowTracking' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'pipelines.externalMetadata.enabled' = 'true')

マテリアライズドビューの場合は、代わりに同等の USING ICEBERG 構文を使用できます。

SQL

CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

パイプライン管理対象のデータセットについては、上記のパイプライン更新手順を使用して Iceberg プロパティを適用してください。スタンドアロンの Databricks SQL オブジェクトの場合は、更新されたプロパティを使用してオブジェクト定義を再実行してください。マテリアライズドビューには CREATE OR REPLACE MATERIALIZED VIEW を、ストリーミングテーブルには CREATE OR REFRESH STREAMING TABLE を使用します。データセットのプロパティを表示するには、DESCRIBE DETAIL または DESCRIBE EXTENDED SQL ステートメントを使用します。

外部データアクセスのトラブルシューティング

外部メタデータが古いと思われる場合、テーブルに対する MODIFY 権限を持つプリンシパルは、Databricks Runtime 17.3 以降を使用して、共有クラスターコンピュート上でメタデータの更新を手動で Trigger できます：

SQL

REPAIR TABLE <catalog>.<schema>.<table-name> SYNC METADATA;

テーブル詳細ページのカタログエクスプローラー UI で、Iceberg メタデータの存在を確認できます。または、SQL エディタまたは Databricks ノートブックで次のコマンドを実行します。

SQL

DESCRIBE DETAIL <catalog>.<schema>.<table-name>;
DESCRIBE EXTENDED <catalog>.<schema>.<table-name>;

ストリーミングテーブルについては、Iceberg メタデータのバージョンと最新のストリーミングテーブルのバージョンを比較してください。マテリアライズドビューのバージョン比較はまだ利用できません。

外部クライアントからのデータの読み取り

以降のセクションでは、さまざまなクライアントや環境からデータセットを読み取る方法の例を紹介します。

セットアップの詳細については、DeltaクライアントアクセスおよびIcebergクライアントアクセスを参照してください。

Spark Delta Reader で Unity REST API を使用

Apache Spark™ バージョン 4.0 以降を使用してください。https://spark.apache.org/downloads.html からダウンロードできます。

1. お使いのクラウドプロバイダーに応じて、Delta 4.0とUnity Catalogを使用してSpark SQLシェルを起動するには、次のコマンドを実行します。

AWS

Shell

bin/spark-sql \
    --packages org.apache.spark:spark-hadoop-cloud_2.13:4.0.0,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.s3.impl=org.apache.hadoop.fs.s3a.S3AFileSystem \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

Azure

Shell

bin/spark-sql \
    --packages org.apache.hadoop:hadoop-azure:3.3.6,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

GCP

Shell

bin/spark-sql \
    --packages io.unitycatalog:unitycatalog-spark_2.13:0.3.1  \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFileSystem \
    --conf spark.hadoop.fs.AbstractFileSystem.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFS \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

2. SQLシェルから、Spark SQLでデータセットにアクセスできるようになりました。例えば：

   Shell

   spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Snowflake Iceberg リーダーを使用します

Snowflakeでは、Icebergリーダーを利用できます。これには、Snowflake での Iceberg v3 のサポートが必要です。

1. Snowflake で Iceberg REST カタログをセットアップします。

   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-table-name>';

2. Snowflake SQL からデータセットにアクセスします。

   SQL

   ALTER ICEBERG TABLE my_table REFRESH;
   SELECT * FROM my_table;

Spark Iceberg リーダーで Iceberg REST カタログを使用してください。

Apache Spark™ バージョン 4.0 以降を使用してください。https://spark.apache.org/downloads.html からダウンロードできます。

1. AWS で、Iceberg v3 を使用して Spark SQL シェルを起動するには、次のコマンドを実行します。

   Shell

   bin/spark-sql \
     --packages org.apache.iceberg:iceberg-spark-runtime-4.0_2.13:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \
     --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
     --conf spark.sql.catalog.<uc-catalog-name>=org.apache.iceberg.spark.SparkCatalog \
     --conf spark.sql.catalog.<uc-catalog-name>.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
     --conf spark.sql.catalog.<uc-catalog-name>.type=rest \
     --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url>/api/2.1/unity-catalog/iceberg-rest \
     --conf spark.sql.catalog.<uc-catalog-name>.token='<PAT>' \
     --conf spark.sql.catalog.<uc-catalog-name>.warehouse=<uc-catalog-name> \
     --conf spark.sql.iceberg.vectorization.enabled=false

2. Spark SQL からデータセットにアクセスできます。

   Shell

   spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

互換モードからの移行

現在、互換モードを使用してデータセットを共有している場合は、外部データアクセスへ移行できます。

1. データセットへのアクセスを有効にする方法の手順に従って、この機能を有効にしてください。
2. 互換モードを無効にしてください。互換モードを無効にするを参照してください。

制限事項：

以下は、ストリーミングテーブルとマテリアライズドビューの外部データアクセスに関する既知の制限事項です。

• 外部書き込み： パイプラインデータセットへの外部書き込みはサポートされていません。
• パスベースのアクセス： パスベースのアクセス（UC API インターフェースではなくストレージロケーションを介して直接読み取る）を必要とする外部リーダーはサポートされていません。パスベースのアクセスをサポートするには、互換モードを使用できますが、データセットの完全なコピーが必要です。
• セキュリティ機能：外部からの読み取りでは、行レベルのセキュリティまたは列レベルのマスキングはサポートされていません。
• タイムトラベル： この機能による タイムトラベル はサポートされていません。
• Catalog commits (ベータ版): Catalog commits は外部データアクセスと互換性がありません。ストリーミングテーブルまたはマテリアライズドビューで外部データアクセスを使用するには、最初に catalog commit を無効にする必要があります。
• ファブリック: Microsoft Fabricからの読み取りはサポートされていません。