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 ファイルを見つける必要があります。この解決プロセスは以下のように機能します。
Candidate Search (in Priority Order)
-
直接パスの指定:
iceberg_metadata_file_path
が設定されている場合、システムはこのパスを Iceberg テーブルのディレクトリパスと結合して使用します。- この設定が提供されると、他のすべての解決設定は無視されます。
-
テーブル UUID マッチング:
iceberg_metadata_table_uuid
が指定されている場合、システムは:metadata
ディレクトリの.metadata.json
ファイルのみを確認します。- 指定された UUID(大文字と小文字を区別しない)に一致する
table-uuid
フィールドを含むファイルをフィルタリングします。
-
デフォルト検索:
- 上記の設定が提供されていない場合、
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
のエイリアスです。