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

iceberg Table Function

Apache Iceberg テーブルへの読み取り専用のテーブルのようなインターフェースを提供します。Amazon S3、Azure、HDFS、またはローカルに保存されたテーブルに対応しています。

Syntax​

Arguments​

引数の説明は、テーブル関数 s3、azureBlobStorage、HDFS、および file の引数の説明に一致します。 format は Iceberg テーブル内のデータファイルの形式を示します。

Returned value​

指定された Iceberg テーブルのデータを読み取るための指定された構造を持つテーブル。

Example​

参考

ClickHouse は現在、icebergS3、icebergAzure、icebergHDFS、および icebergLocal テーブル関数と IcebergS3、icebergAzure、IcebergHDFS、IcebergLocal テーブルエンジンを介して、Iceberg フォーマットの v1 および v2 の読み取りをサポートしています。

Defining a named collection​

URL および資格情報を保存するために名前付きコレクションを構成する例を以下に示します。

Schema Evolution​

現在、CH の助けを借りて、時間の経過とともにスキーマが変更された Iceberg テーブルを読み取ることができます。現在、列が追加および削除され、順序が変更されたテーブルの読み取りをサポートしています。また、値が必須の列を NULL を許可する列に変更することもできます。さらに、次の単純タイプに対する許可された型変換をサポートしています。

  • int -> long
  • float -> double
  • decimal(P, S) -> decimal(P', S) ただし、P' > P。

現在、ネストされた構造や配列およびマップ内の要素の型を変更することはできません。

Partition Pruning​

ClickHouse は Iceberg テーブルに対する SELECT クエリ中のパーティショニング プルーニングをサポートしています。これは、無関係なデータファイルをスキップすることによってクエリのパフォーマンスを最適化するのに役立ちます。パーティショニング プルーニングを有効にするには、use_iceberg_partition_pruning = 1 を設定します。Iceberg のパーティショニング プルーニングに関する詳細は、 https://iceberg.apache.org/spec/#partitioning を参照してください。

Time Travel​

ClickHouse は Iceberg テーブル用の時間旅行をサポートしており、特定のタイムスタンプまたはスナップショット ID を使用して過去のデータをクエリできます。

Basic usage​

注意: 同じクエリ内で iceberg_timestamp_ms と iceberg_snapshot_id の両方のパラメータを指定することはできません。

Important considerations​

  • スナップショット は通常、以下のような場合に作成されます：

    • 新しいデータがテーブルに書き込まれるとき
    • 何らかのデータ圧縮が行われるとき

  • スキーマの変更は通常、スナップショットを作成しません - これは、スキーマが進化したテーブルで時間旅行を使用する際に重要な動作をもたらします。

Example scenarios​

すべてのシナリオは Spark で記述されています。CH はまだ Iceberg テーブルへの書き込みをサポートしていません。

Scenario 1: Schema Changes Without New Snapshots​

この操作のシーケンスを考えてみましょう：

異なるタイムスタンプでのクエリ結果：

  • ts1 および ts2 の場合：元の 2 列のみが表示されます。
  • ts3 の場合：3 列すべてが表示され、最初の行の価格は NULL です。

Scenario 2: Historical vs. Current Schema Differences​

現在の瞬間での時間旅行クエリは、現在のテーブルとは異なるスキーマを示す可能性があります：

このようになるのは、ALTER TABLE が新しいスナップショットを作成せず、現在のテーブルでは Spark が最新のメタデータファイルから schema_id の値を取得するためです。

Scenario 3: Historical vs. Current Schema Differences​

時間旅行を行うと、データが書き込まれる前のテーブルの状態を取得することはできません：

ClickHouse の動作は Spark と一致しています。Spark の Select クエリを Clickhouse の Select クエリと置き換えれば、同じように動作します。

Metadata File Resolution​

ClickHouse の iceberg テーブル関数を使用する際、システムは Iceberg テーブル構造を記述する正しい metadata.json ファイルを見つける必要があります。この解決プロセスは以下のように機能します。

  1. 直接パスの指定:

    • iceberg_metadata_file_path が設定されている場合、システムはこのパスを Iceberg テーブルのディレクトリパスと結合して使用します。
    • この設定が提供されると、他のすべての解決設定は無視されます。

  2. テーブル UUID マッチング:

    • iceberg_metadata_table_uuid が指定されている場合、システムは：
      • metadata ディレクトリの .metadata.json ファイルのみを確認します。
      • 指定された UUID（大文字と小文字を区別しない）に一致する table-uuid フィールドを含むファイルをフィルタリングします。

  3. デフォルト検索:

    • 上記の設定が提供されていない場合、metadata ディレクトリ内のすべての .metadata.json ファイルが候補になります。

Selecting the Most Recent File​

上記のルールを使用して候補ファイルを特定した後、システムはどれが最も新しいかを判断します：

  • iceberg_recent_metadata_file_by_last_updated_ms_field が有効な場合：

    • last-updated-ms 値が最も大きいファイルが選択されます。

  • そうでない場合：

    • バージョン番号が最も高いファイルが選択されます。
    • （バージョンは、V.metadata.json または V-uuid.metadata.json の形式のファイル名に表示されます）

注意: すべての設定はテーブル関数の設定です（グローバルまたはクエリレベルの設定ではなく）、以下のように指定する必要があります：

注意: Iceberg カタログは通常、メタデータ解決を処理しますが、ClickHouse の iceberg テーブル関数は S3 に保存されているファイルを Iceberg テーブルとして直接解釈します。このため、これらの解決ルールを理解することが重要です。

Metadata cache​

Iceberg テーブルエンジンとテーブル関数は、マニフェストファイル、マニフェストリスト、およびメタデータ JSON の情報を保存するメタデータキャッシュをサポートしています。キャッシュはメモリに保存されます。この機能は use_iceberg_metadata_files_cache を設定することで制御されており、デフォルトでは有効です。

Aliases​

テーブル関数 iceberg は現在 icebergS3 のエイリアスです。

See Also​