アクセス方法を選択する
テーブル関数
icebergAzure、icebergLocal、および他のフォーマットの対応する同等物) があります。完全な一覧については、直接クエリ を参照してください。
Paimon では、テーブル関数のみが利用できます。
テーブルエンジン
DataLakeCatalog データベースエンジン
複数要素のテーブル名でのバッククォートカタログでは
database.table 形式の命名がよく使われます。上記の例のように、データベース修飾名をバッククォートで囲んでください。必要な設定
CREATE DATABASE が権限エラーで失敗する場合は、サービスのバージョンを確認してください。
カタログ接続では、カタログタイプごとに専用のフラグがあります。概要については カタログへの接続 を、設定の詳細については DataLakeCatalog reference を参照してください。各カタログのセットアップ手順は カタログガイド にあります。
書き込みでは、Iceberg で allow_insert_into_iceberg が必要です (25.7+、26.2 以降はベータ) 。詳しくは Writing to data lakes を参照してください。Delta Lake で allow_delta_lake_writes が必要です (25.9+) 。support matrix には、各フォーマットと操作にどのフラグが適用されるかが示されています。
クエリパフォーマンスを向上させる
クエリの習慣
WHERE 句では、パーティションカラムに対してフィルタを指定します。Iceberg と Delta Lake はパーティションのメタデータを保持しているため、ClickHouse はクエリプランの作成時に無関係なファイルをスキップできます。フィルタ対象がパーティション仕様に含まれないカラムの場合、ClickHouse は一致するすべてのファイルをスキャンします。
hidden partitioning を使用する Icebergテーブルでは、別個のパーティションカラムや変換後のフィールド名ではなく、テーブルスキーマ内の 元のカラム に対してフィルタを指定してください。テーブルが day(event_time) でパーティション化されている場合は、event_time に条件を追加します。ClickHouse はそのフィルタから、Iceberg の partition spec を使ってパーティションプルーニングを導き出します。Partition pruning と Iceberg spec を参照してください。
SELECT * ではなく、必要なカラムだけを指定してください。ClickHouse はオブジェクトストレージから Parquet をカラム単位で読み取るため、必要なカラムだけを選択すると、転送および解凍するバイト数を削減できます。
選択性の高いフィルターは WHERE に置いてください。ClickHouse 26.2+ では、PREWHERE が Iceberg やその他のレイクテーブルの読み取りでもサポートされており、残りのカラムを読む前に Parquet レイヤーでフィルタリングを行えます。パーティションプルーニングは、PREWHERE だけでなく、引き続きパーティションカラムに対するフィルタリングに依存します。
位置 deletes または等価 deletes が多い Iceberg テーブルでは、スキャン時に merge-on-read フィルタリングが適用されます。マニフェストのプルーニングだけから想定されるよりも、ファイルごとの処理が増えると考えてください。
マルチノード構成では、cluster table functions を使用して、レプリカ間でファイル読み取りを分散してください。
マルチノードクラスターでの並列読み取り
'default') 。対応フォーマットごとにクラスター版が用意されています。
クラスター読み取りは、ほかのパフォーマンス設定と組み合わせることもできます。
バッチ読み取りの対象をスナップショットに限定する
- Iceberg では、iceberg_snapshot_id または iceberg_timestamp_ms (25.4+) を使用して特定時点のビューを読み取ります。追記専用テーブルでは、スナップショット設定を
WHEREのパーティションフィルターと組み合わせてください。実行間のスナップショット ID を確認するには、system.iceberg_history (25.6+) を使用します。 - Delta Lake では、delta_lake_snapshot_start_version と delta_lake_snapshot_end_version (25.12+) を使用して、2 つのバージョン間の変更を読み取ります。delta_lake_snapshot_version (25.8+) を使用すると、単一のスナップショットを読み取れます。CDF の例については、Delta change data feed を参照してください。
Parquetファイルをローカルにキャッシュする
enable_filesystem_cache = 0 を設定してください。
Apache Iceberg
読み取り設定
カタログのレイテンシを抑える
- テーブル作成時に iceberg_metadata_async_prefetch_period_ms を設定し、バックグラウンドでメタデータを事前フェッチします。
- クエリで iceberg_metadata_staleness_ms (26.3+) を設定し、カタログへのラウンドトリップを省く代わりに、やや古いメタデータを許容します。
0 の staleness 値では、常に最新のメタデータを取得します。テーブルの変更頻度が低く、読み取り負荷の高いワークロードでは、この期間を長くしてください。
ClickHouse が誤ったメタデータファイルを選択する場合 (テーブルパスに複数の .metadata.json ファイルがある場合) は、テーブル作成時に iceberg_metadata_file_path (25.4+) または iceberg_metadata_table_uuid を使って参照先を固定してください。メタデータファイルの解決 を参照してください。
タイムトラベル
Iceberg への書き込み
データレイクへの書き込み と Iceberg エンジンのリファレンス を参照してください。
Delta Lake
Delta Kernel
読み取り設定
deletion vectors を持つテーブル (26.2+) では、読み取り時に行レベルのフィルタリングが適用されます。ClickHouse はこれを自動的に処理しますが、DV の多いテーブルでは、スキャン時にファイルごとの処理負荷が増えます。
Delta の変更データフィード
delta.enableChangeDataFeed) が有効になっている必要があります。開始バージョンと終了バージョンの両方をクエリ設定で指定してください。終了バージョンだけを指定するとエラーになります。
_change_type、_commit_version、_commit_timestamp) が含まれます。ターゲットテーブルに読み込む前に、これらを処理してください。一般的なスナップショットのパターンについては、バッチ読み取りをスナップショットにバインドするを参照してください。
Delta Lake への書き込み
データレイククエリのデバッグ
カタログ接続を確認する
CREATE DATABASE と DataLakeCatalog では認証情報は検証されません。カタログへの接続が切れていても、database 自体は存在し得ます。ClickHouse 26.4 以降では、軽量なヘルスチェックを実行してください。
SHOW TABLES FROM my_lake を実行して接続できることを確認し、error メッセージを確認します。解決されたストレージ path と engine の種類を確認するには、バッククォートで囲んだ table 名を指定して SHOW CREATE TABLE を使用します。
system.tablesに表示されない場合は、show_remote_databases_in_system_tables (25.8+) を有効にしてください。カタログのテーブルは、デフォルトではシステムのイントロスペクションの対象外になっています。26.6より前のバージョンでは、以前の名称であるshow_data_lake_catalogs_in_system_tablesを使用してください。
読み取られているファイルを確認する
_path、_file、_size、_time、_etag) が公開されます。_path でグループ化すると、パーティションプルーニングが機能しているか、あるいはクエリが想定以上に多くのファイルをスキャンしているかを確認できます。隠しパーティション化を使用する Iceberg テーブルでは、別のパーティションカラムではなく、元のカラム (たとえば event_time) で絞り込んでください。
スキャン量を確認する
read_rows と read_bytes を比較します。ReadBufferFromS3Bytes や CachedReadBufferReadFromCacheBytes などの ProfileEvents を見ると、オブジェクトストレージ由来のデータ量とローカル cache 由来のデータ量を確認できます。query_log と EXPLAIN の詳しい手順については、クエリ最適化 を参照してください。
ベンチマーク時には、cache ヒットによって実行ごとの差が見えにくくならないよう、enable_filesystem_cache を無効にしてください。
メタデータログ
ログを有効にしてクエリを実行し、ログを flush してから、その
query_id のエントリを確認します。
clusterAllReplicas を使用してください。
Iceberg の詳細なログレベルでは、マニフェストリストとファイルのメタデータのキャッシュが無効になるため、同じテーブルに対する後続のクエリが遅くなります。詳細度を高くするのは、実際に調査しているときだけにしてください。Delta Lake の述語に関する問題については、カーネルがフィルターをプッシュダウンできない場合に即座に失敗させるため、delta_lake_throw_on_engine_predicate_error (25.8+) を有効にしてください。
カラムの詳細と詳細度オプションについては、iceberg_metadata_log と delta_lake_metadata_log のリファレンスページを参照してください。
次のステップ
- はじめに — 直接クエリから書き戻しまでを一通り解説
- 直接クエリ — 4 つのフォーマットすべてに対応するテーブル関数、エンジン、クラスター構成
- カタログへの接続 — Unity Catalog を使用した
DataLakeCatalogの Setup - データレイクへの書き込み — Iceberg と Delta Lake にデータを書き戻す
- サポートマトリクス — フォーマット、カタログ、ストレージバックエンドごとの機能比較