OneLake で Iceberg テーブルを使用する

[アーティクル]
11/18/2024

Microsoft OneLake では、Apache Iceberg テーブルへのショートカットを作成して、さまざまな幅広い Fabric ワークロードで使用できます。この機能は、メタデータ仮想化と呼ばれる機能によって実現されます。これにより、ショートカットから見ると Iceberg テーブルをDelta Lake テーブルとして解釈することができます。 Iceberg テーブルフォルダーへのショートカットを作成すると、OneLake によって、そのテーブルに対応する Delta Lake メタデータ (Delta ログ) が自動的に生成され、Delta Lake メタデータにショートカット経由でアクセスできるようになります。

重要

この機能はプレビュー中です。

Delta Lake メタデータの仮想化を示す図。

この記事には Snowflake から OneLake に Iceberg テーブルを書き込むためのガイダンスが含まれていますが、この機能は Parquet データファイルを含む Iceberg テーブルを操作することを目的としています。

Iceberg テーブルへのテーブルショートカットを作成する

OneLake ショートカットでサポートされているストレージの場所に Iceberg テーブルが既にある場合は、次の手順に従ってショートカットを作成し、Iceberg テーブルを Delta Lake 形式で表示するようにします。

Iceberg テーブルを見つけます。 Iceberg テーブルが格納されている場所 (Azure Data Lake Storage、OneLake、Amazon S3、Google Cloud Storage、S3 互換のストレージサービスなど) を見つけます。

Note

Snowflake を使用していて、Iceberg テーブルが格納されている場所がわからない場合は、次のステートメントを実行して Iceberg テーブルの格納場所を確認できます。

SELECT SYSTEM$GET_ICEBERG_TABLE_INFORMATION('<table_name>');

このステートメントを実行すると、Iceberg テーブルのメタデータファイルへのパスが返されます。このパスにより、どのストレージアカウントに Iceberg テーブルが含まれているかが示されます。たとえば、Azure Data Lake Storage に格納されている Iceberg テーブルのパスを見つけるための関連情報が次のものであるとします。

{"metadataLocation":"azure://<storage_account_path>/<path_within_storage>/<table_name>/metadata/00001-389700a2-977f-47a2-9f5f-7fd80a0d41b2.metadata.json","status":"success"}

Iceberg テーブルフォルダーには、metadata フォルダーが含まれている必要があります。このフォルダー自体には、.metadata.json で終わるファイルが少なくとも 1 つ含まれています。
Fabric lakehouse で、スキーマ非対応のレイクハウスの [テーブル] 領域に新しいショートカットを作成します。

Note

レイクハウスの Tables フォルダーの下に dbo などのスキーマが表示される場合、そのレイクハウスはスキーマ対応であり、この機能との互換性はまだありません。
ショートカットのターゲットパスには、Iceberg テーブルフォルダーを選択します。 Iceberg テーブルフォルダーには metadata フォルダーと data フォルダーが含まれています。
ショートカットが作成されると、このテーブルがレイクハウスの Delta Lake テーブルとして自動的に反映され、Fabric 全体で使用できるようになります。

新しい Iceberg テーブルのショートカットが使用可能なテーブルとして表示されない場合は、「トラブルシューティング」セクションを確認してください。

Snowflake を使用して OneLake に Iceberg テーブルを書き込む

Azure で Snowflake を使用する場合は、次の手順に従って、Iceberg テーブルを OneLake に書き込むことができます。

Fabric キャパシティが Snowflake インスタンスと同じ Azure の場所にあることを確認します。

Fabric レイクハウスに関連付けられている Fabric キャパシティの場所を特定します。レイクハウスを含む Fabric ワークスペースの設定を開きます。

Azure アカウントインターフェイスの Snowflake の左下隅で、Snowflake アカウントの Azure リージョンを確認します。

これらのリージョンが異なる場合は、Snowflake アカウントと同じリージョン内の別の Fabric キャパシティを使用する必要があります。
レイクハウスの [ファイル] 領域のメニューを開き、[プロパティ] を選択し、そのフォルダーの URL (HTTPS パス) をコピーします。
Fabric テナント ID を特定します。 Fabric UI の右上隅にあるユーザープロファイルを選択し、[テナント名] の横にある情報バブルにマウスポインターを合わせます。 テナント ID をコピーします。
Snowflake で、レイクハウスの [ファイル] フォルダーへのパスを使用して EXTERNAL VOLUME を設定します。 Snowflake 外部ボリュームの設定の詳細については、こちらを参照してください。

Note

Snowflake では URL スキームを azure:// にする必要があるため、https:// を azure:// に必ず変更してください。
```
CREATE OR REPLACE EXTERNAL VOLUME onelake_exvol
STORAGE_LOCATIONS =
(
    (
        NAME = 'onelake_exvol'
        STORAGE_PROVIDER = 'AZURE'
        STORAGE_BASE_URL = 'azure://<path_to_Files>/icebergtables'
        AZURE_TENANT_ID = '<Tenant_ID>'
    )
);
```
このサンプルでは、この外部ボリュームを使用して作成されたすべてのテーブルは、Files/icebergtables フォルダー内の Fabric レイクハウスに格納されます。
外部ボリュームが作成されたら、次のコマンドを実行して、同意 URL と、Snowflake が OneLake への書き込みに使用するアプリケーションの名前を取得します。このアプリケーションは、Snowflake アカウント内の他のすべての外部ボリュームで使用されます。
```
DESC EXTERNAL VOLUME onelake_exvol;
```
このコマンドの出力では、AZURE_CONSENT_URL プロパティと AZURE_MULTI_TENANT_APP_NAME プロパティが返されます。両方の値を書き留めます。 Azure マルチテナントアプリ名は <name>_<number> のようになっていますが、キャプチャする必要があるのは <name> の部分のみです。
新しいブラウザータブで、前の手順の同意 URL を開きます。続行する場合は、求められたら、必要なアプリケーションのアクセス許可に同意します。
Fabric に戻り、ワークスペースを開き、[アクセスの管理] を選択し、続いて [ユーザーまたはグループの追加] を選択します。 Snowflake 外部ボリュームで使用されるアプリケーションに、ワークスペース内のレイクハウスにデータを書き込むのに必要なアクセス許可を付与します。 共同作成者ロールを付与することをお勧めします。
Snowflake に戻り、新しい外部ボリュームを使用して Iceberg テーブルを作成します。
```
CREATE OR REPLACE ICEBERG TABLE MYDATABASE.PUBLIC.Inventory (
    InventoryId int,
    ItemName STRING
)
EXTERNAL_VOLUME = 'onelake_exvol'
CATALOG = 'SNOWFLAKE'
BASE_LOCATION = 'Inventory/';
```
このステートメントを使用すると、"Inventory" という名前の新しい Iceberg テーブルフォルダーが、外部ボリュームで定義されているフォルダーパス内に作成されます。

Iceberg テーブルにデータを追加します。

INSERT INTO MYDATABASE.PUBLIC.Inventory
VALUES
(123456,'Amatriciana');

最後に、同じレイクハウスの [テーブル] 領域で、Iceberg テーブルへの OneLake ショートカットを作成できます。そのショートカットを使用すると、Iceberg テーブルは、Fabric ワークロード全体で使用するための Delta Lake テーブルとして表されます。

トラブルシューティング

次のヒントは、Iceberg テーブルがこの機能と互換性があることを確認するのに役立ちます。

Iceberg テーブルのフォルダー構造を確認する

適切なストレージエクスプローラーツールで Iceberg フォルダーを開き、Iceberg フォルダーのディレクトリ一覧が元の場所にあることを確認します。次の例のようなフォルダー構造が表示されます。

../
|-- MyIcebergTable123/
    |-- data/
        |-- snow_A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- snow_A5WYPKGO_2o_AAIBON_h9Rc_0_1_003.parquet
    |-- metadata/
        |-- 00000-1bdf7d4c-dc90-488e-9dd9-2e44de30a465.metadata.json
        |-- 00001-08bf3227-b5d2-40e2-a8c7-2934ea97e6da.metadata.json
        |-- 00002-0f6303de-382e-4ebc-b9ed-6195bd0fb0e7.metadata.json
        |-- 1730313479898000000-Kws8nlgCX2QxoDHYHm4uMQ.avro
        |-- 1730313479898000000-OdsKRrRogW_PVK9njHIqAA.avro
        |-- snap-1730313479898000000-9029d7a2-b3cc-46af-96c1-ac92356e93e9.avro
        |-- snap-1730313479898000000-913546ba-bb04-4c8e-81be-342b0cbc5b50.avro

メタデータフォルダーが表示されない場合、またはこの例に示されている拡張子のファイルが表示されない場合は、適切に生成された Iceberg テーブルがない可能性があります。

変換ログを確認する

Iceberg テーブルを Delta Lake テーブルとして仮想化すると、_delta_log/ という名前のフォルダーがショートカットフォルダー内に存在するようになります。このフォルダーには、変換が正常に行われた後の Delta Lake 形式のメタデータ (Delta ログ) が含まれています。

このフォルダーには、最新の変換試行の成功または失敗に関する詳細を含む latest_conversion_log.txt ファイルも含まれています。

ショートカットを作成した後にこのファイルの内容を確認するには、レイクハウスの [テーブル] 領域にある Iceberg テーブルショートカットのメニューを開き、[ファイルの表示] を選択します。

[ファイルの表示] メニュー項目のスクリーンショット。

次の例のような構造が表示されます。

Tables/
|-- MyIcebergTable123/
    |-- data/
        |-- <data files>
    |-- metadata/
        |-- <metadata files>
    |-- _delta_log/   <-- Virtual folder. This folder doesn't exist in the original location.
        |-- 00000000000000000000.json
        |-- latest_conversion_log.txt   <-- Conversion log with latest success/failure details.

変換ログファイルを開き、最新の変換時間、または失敗の詳細を確認します。変換ログファイルが表示されない場合、変換は試行されませんでした。

変換が試行されなかった場合

変換ログファイルが表示されない場合、変換は試行されませんでした。変換が試行されない一般的な理由を次に 2 つ示します。

ショートカットが適切な場所に作成されなかった。

Iceberg テーブルへのショートカットを Delta Lake 形式に変換するには、スキーマ非対応のレイクハウスのフォルダーの直下にショートカットが配置されている必要があります。テーブルを Delta Lake テーブルとして自動的に仮想化する場合は、ショートカットを [ファイル] セクションや別のフォルダーの下に配置してはいけません。
ショートカットのターゲットパスが Iceberg フォルダーパスではない。

ショートカットを作成する際に、[ターゲットの保存場所] で選択するフォルダーパスは Iceberg テーブルフォルダーでなければなりません。このフォルダーには metadata フォルダーと data フォルダーが含まれています。

制限と考慮事項

この機能を使用する際には、次の一時的な制限事項に注意してください。

サポートされているデータ型

次の Iceberg 列のデータ型は、この機能を使用して対応する Delta Lake 型にマップされます。

Iceberg 列の型	Delta Lake 列の型	Comments
`int`	`integer`
`long`	`long`	「型の幅の問題」を参照してください。
`float`	`float`
`double`	`double`	「型の幅の問題」を参照してください。
`decimal(P, S)`	`decimal(P, S)`	「型の幅の問題」を参照してください。
`boolean`	`boolean`
`date`	`date`
`timestamp`	`timestamp_ntz`	`timestamp` Iceberg データ型にはタイムゾーン情報が含まれません。 `timestamp_ntz` Delta Lake 型は、Fabric ワークロード全体で完全にはサポートされていません。タイムゾーンを含むタイムスタンプを使用することをお勧めします。
`timestamptz`	`timestamp`	Snowflake でこの型を使用するには、Iceberg テーブルの作成時に列の型として `timestamp_ltz` を指定します。 Snowflake でサポートされている Iceberg データ型の詳細については、こちらを参照してください。
`string`	`string`
`binary`	`binary`

型の幅の問題

Snowflake を使用して Iceberg テーブルに書き込む場合で、テーブルに有効桁数が >= 10 の列の型 INT64、double、または Decimal が含まれている場合、結果の仮想 Delta Lake テーブルは、すべての Fabric エンジンでは必ずしも使用できない可能性があります。次のようなエラーが表示される可能性があります。
```
Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
```
この問題の解決に取り組んでいます。

回避策: Lakehouse テーブルプレビュー UI を使用していて、この問題が発生する場合は、SQL エンドポイントビュー (右上隅の [Lakehouse ビューの選択]、[SQL エンドポイントへの切り替え] を選択) に切り替えて、そこからテーブルをプレビューすることで、このエラーを解決できます。その後、Lakehouse ビューに戻ると、テーブルのプレビューが適切に表示されます。

Spark ノートブックまたはジョブを実行していて、この問題が発生する場合は、spark.sql.parquet.enableVectorizedReader Spark 構成を false に設定することで、このエラーを解決できます。 Spark ノートブックで実行する PySpark コマンドの例を次に示します。
```
spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
```
Iceberg テーブルメタデータストレージはポータブルではない

Iceberg テーブルのメタデータファイルは、相互の参照を絶対パス参照を使用して行います。 Iceberg のメタデータファイルを書き換えないで Iceberg テーブルのフォルダーの内容をコピーしたり別の場所に移動したりすると、この OneLake 機能を含め、Iceberg の読み取りができなくなります。

対処法:

この機能を使用するために Iceberg テーブルを別の場所に移動する必要がある場合は、最初に Iceberg テーブルを書き込んだツールを使用して、目的の場所に新しい Iceberg テーブルを書き込みます。
Iceberg テーブルはルートレベルよりも深くなくてはならない

ストレージ内の Iceberg テーブルフォルダーは、バケットまたはコンテナーレベルより深いディレクトリに配置する必要があります。バケットまたはコンテナーのルートディレクトリに直接格納されている Iceberg テーブルは、Delta Lake 形式に仮想化されない可能性があります。

この要件を取り除くよう改善に取り組んでいます。

対処法:

Iceberg テーブルが、バケットまたはコンテナーのルートディレクトリより深いディレクトリに確実に格納されているようにします。
Iceberg テーブルフォルダーに含まれているメタデータファイルのセットは 1 つのみにする必要がある

Snowflake で Iceberg テーブルをドロップして再作成しても、メタデータファイルはクリーンアップされません。この動作は、Snowflake の UNDROP 機能をサポートするものです。ただし、ショートカットはフォルダーを直接指しており、そのフォルダー内に複数のメタデータファイルセットが含まれるようになったため、古いテーブルのメタデータファイルを削除するまでテーブルを変換できません。

現在のところ、このシナリオでは変換の試行が行われるため、古いテーブルの内容とスキーマ情報が仮想化された Delta Lake テーブルで表示される可能性があります。

Iceberg テーブルのメタデータフォルダーに複数のメタデータファイルセットが見つかった場合には変換が失敗するようにする修正に取り組んでいます。

対処法:

変換されたテーブルに正しいバージョンのテーブルが反映されるようにするには、次を確認します。
- 同一のフォルダー内に複数の Iceberg テーブルを格納していないことを確認します。
- Iceberg テーブルをドロップした後、テーブルを再作成する前に Iceberg テーブルのフォルダーの内容をクリーンアップします。
メタデータの変更は即座に反映されない

列の追加、列の削除、列の名前変更、列の型の変更など、Iceberg テーブルにメタデータの変更を加えた場合、データの変更 (データ行の追加など) が行われるまで、テーブルの再変換は行われない可能性があります。

最新のメタデータの変更が含まれている適切な最新のメタデータファイルをピックアップするようにする修正に取り組んでいます。

対処法:

Iceberg テーブルにスキーマ変更を加えた後、データ行を追加したり、データに他の変更を加えたりします。その変更後、Fabric でテーブルをリフレッシュして最新のビューを確認できるようになります。
スキーマ対応ワークスペースはまだサポートされていない

スキーマ対応のレイクハウス内に Iceberg ショートカットを作成した場合、そのショートカットに対して変換は行われません。

この制限を取り除くよう改善に取り組んでいます。

対処法:

この機能については、非スキーマ対応のレイクハウスを使用します。この設定は、レイクハウスの作成時に構成できます。
リージョンの可用性の制限事項

この機能は、次のリージョンではまだ使用できません。
- カタール中部
- ノルウェー西部
対処法:

他のリージョンの Fabric 容量にアタッチされているワークスペースでは、この機能を使用できます。 Microsoft Fabric が使用可能なリージョンの完全な一覧を確認する。
プライベートリンクはサポートされていない

現在、この機能は、プライベートリンクが有効になっているテナントまたはワークスペースではサポートされていません。

この制限を取り除くよう改善に取り組んでいます。
テーブルサイズの制限

この機能でサポートされている Iceberg テーブルのサイズには一時的な制限があります。サポートされる Parquet データファイルの最大数は、約 5,000 個のデータファイル、または約 10 億行のうち、どちらか先に到達した方です。

この制限を取り除くよう改善に取り組んでいます。
OneLake ショートカットは同一リージョンでなければならない

この機能の使用には、OneLake の場所を指すショートカットを使用する場合に一時的な制限があります。ショートカットのターゲットの場所は、ショートカット自体と同じリージョンになければなりません。

この要件を取り除くよう改善に取り組んでいます。

対処法:

別のレイクハウスの Iceberg テーブルへの OneLake ショートカットがある場合は、他のレイクハウスが同じリージョンのキャパシティに関連付けられているようにしてください。

Fabric と OneLake のセキュリティの詳細について説明します。
OneLake のショートカットの詳細を参照する

次の方法で共有

OneLake で Iceberg テーブルを使用する

Iceberg テーブルへのテーブルショートカットを作成する

Snowflake を使用して OneLake に Iceberg テーブルを書き込む

トラブルシューティング

Iceberg テーブルのフォルダー構造を確認する

変換ログを確認する

変換が試行されなかった場合

制限と考慮事項

フィードバック

その他のリソース

次の方法で共有

OneLake で Iceberg テーブルを使用する

Iceberg テーブルへのテーブル ショートカットを作成する

Snowflake を使用して OneLake に Iceberg テーブルを書き込む

トラブルシューティング

Iceberg テーブルのフォルダー構造を確認する

変換ログを確認する

変換が試行されなかった場合

制限と考慮事項

関連するコンテンツ

フィードバック

その他のリソース

Iceberg テーブルへのテーブルショートカットを作成する