Skip to main content
スタートガイドでは、Apache IcebergDelta LakeApache HudiApache Paimon を初めてクエリする手順を説明します。セットアップが完了したら、このページを使って適切なアクセスパターンを選び、クエリパフォーマンスを最適化し、本番環境でデータレイクのクエリをデバッグしてください。

アクセス方法を選択する

テーブル関数

保存先がわかっていて永続テーブルの定義が不要な場合は、ストレージのパスと認証情報をインラインで指定します。
AWS S3 と GCS には S3 バリアントを使用します。Azure とローカルファイルシステムには専用のバリアント (icebergAzureicebergLocal、および他のフォーマットの対応する同等物) があります。完全な一覧については、直接クエリ を参照してください。 Paimon では、テーブル関数のみが利用できます。

テーブルエンジン

同じパスに対して繰り返しクエリを実行する場合は、テーブルエンジンを使ってテーブルを作成します。ClickHouse はパスと認証情報をテーブルのメタデータに保存するため、毎回関数呼び出しを組み立て直すことなく、通常のテーブル名に対してクエリを実行できます。
テーブルエンジンは、データキャッシュメタデータキャッシュ を含め、テーブル関数と同じ読み取り機能をサポートしています。データが ClickHouse 内で複製されることはありません。チームでアクセスを共有する場合や、同じテーブルに対して定期的なジョブを実行する場合は、テーブルエンジンが便利です。

DataLakeCatalog データベースエンジン

外部のデータカタログにテーブルを登録したら、ClickHouse を一度接続するだけで済みます。接続の作成後にアップストリームで追加されたテーブルも含め、すべてのカタログテーブルが自動的に ClickHouse テーブルとして表示されます。
多数のテーブルを管理する場合や複数のカタログを扱う場合は、個別にテーブル定義を作成するよりも、この方法のほうがスケーラブルです。カタログへの接続カタログガイド を参照してください。
複数要素のテーブル名でのバッククォートカタログでは 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 には、各フォーマットと操作にどのフラグが適用されるかが示されています。

クエリパフォーマンスを向上させる

このページのバージョン番号は、ClickHouse のリリースバージョン (Cloud およびセルフマネージド) に対応しています。設定や機能を有効にする前に、ご利用中のサービスのバージョンを確認してください。 Lake のクエリパフォーマンスは、ClickHouse がオブジェクトストレージから読み取るメタデータの量と Parquet ファイル数に左右されます。他の ClickHouse テーブルと同様に、パーティションカラムで絞り込み、取得するカラムを少なくすることで、クエリパフォーマンスを向上できます。

クエリの習慣

WHERE 句では、パーティションカラムに対してフィルタを指定します。Iceberg と Delta Lake はパーティションのメタデータを保持しているため、ClickHouse はクエリプランの作成時に無関係なファイルをスキップできます。フィルタ対象がパーティション仕様に含まれないカラムの場合、ClickHouse は一致するすべてのファイルをスキャンします。 hidden partitioning を使用する Icebergテーブルでは、別個のパーティションカラムや変換後のフィールド名ではなく、テーブルスキーマ内の 元のカラム に対してフィルタを指定してください。テーブルが day(event_time) でパーティション化されている場合は、event_time に条件を追加します。ClickHouse はそのフィルタから、Iceberg の partition spec を使ってパーティションプルーニングを導き出します。Partition pruningIceberg spec を参照してください。
SELECT * ではなく、必要なカラムだけを指定してください。ClickHouse はオブジェクトストレージから Parquet をカラム単位で読み取るため、必要なカラムだけを選択すると、転送および解凍するバイト数を削減できます。 選択性の高いフィルターは WHERE に置いてください。ClickHouse 26.2+ では、PREWHERE が Iceberg やその他のレイクテーブルの読み取りでもサポートされており、残りのカラムを読む前に Parquet レイヤーでフィルタリングを行えます。パーティションプルーニングは、PREWHERE だけでなく、引き続きパーティションカラムに対するフィルタリングに依存します。 位置 deletes または等価 deletes が多い Iceberg テーブルでは、スキャン時に merge-on-read フィルタリングが適用されます。マニフェストのプルーニングだけから想定されるよりも、ファイルごとの処理が増えると考えてください。 マルチノード構成では、cluster table functions を使用して、レプリカ間でファイル読み取りを分散してください。

マルチノードクラスターでの並列読み取り

ClickHouse Cloud とセルフマネージドのマルチノードサービスでは、レイク向けテーブル関数のクラスター版によって Parquet ファイルの読み取りがレプリカ間に分散されます。イニシエーターノードは、ファイルをワーカーに並列に振り分けます。大規模なテーブルに対するバッチ読み取りや定期ロードには、クラスター版を使用してください。シングルノードのデプロイメントでは、通常のテーブル関数で十分です。 クラスター名を第1引数として渡します (ClickHouse Cloud では 'default') 。対応フォーマットごとにクラスター版が用意されています。 クラスター読み取りは、ほかのパフォーマンス設定と組み合わせることもできます。

バッチ読み取りの対象をスナップショットに限定する

レイクテーブルからバッチ読み込みを繰り返す場合は、毎回テーブル全体を再読み取りするのではなく、各実行の対象をスナップショットの範囲に限定してください。範囲を指定しないと、ClickHouse は実行のたびにすべてのバージョンとファイルをスキャンする可能性があり、オブジェクトストレージの読み取り量とクエリ時間が増加します。 前回正常に読み込みが完了した際のスナップショット識別子を保存し、次回の実行ではそれを下限として使用します。

Parquetファイルをローカルにキャッシュする

どちらのフォーマットでも、クエリ間で頻繁に使われる Parquet ファイルをローカルディスクに保持するために、enable_filesystem_cache を利用できます。セルフマネージド環境では、この設定の書き込み先となるストレージを確保するため、サーバー設定で ファイルシステムキャッシュディスク を構成してください。ClickHouse Cloud ではキャッシュは自動的に管理されます。ベンチマーク時には、キャッシュヒットによって実行ごとの差異が見えにくくならないよう、enable_filesystem_cache = 0 を設定してください。

Apache Iceberg

Iceberg の読み取り最適化のほとんどは、デフォルトで有効になっています。以下の設定では、パーティションプルーニング、メタデータキャッシュ、カタログとの往復通信を制御できます。

読み取り設定

カタログのレイテンシを抑える

カタログに接続されたIcebergテーブルでは、キャッシュしない限り、クエリごとにメタデータのフェッチが発生します。次の2つの設定を組み合わせて使います (26.4+) :
  1. テーブル作成時に iceberg_metadata_async_prefetch_period_ms を設定し、バックグラウンドでメタデータを事前フェッチします。
  2. クエリで iceberg_metadata_staleness_ms (26.3+) を設定し、カタログへのラウンドトリップを省く代わりに、やや古いメタデータを許容します。
0staleness 値では、常に最新のメタデータを取得します。テーブルの変更頻度が低く、読み取り負荷の高いワークロードでは、この期間を長くしてください。 ClickHouse が誤ったメタデータファイルを選択する場合 (テーブルパスに複数の .metadata.json ファイルがある場合) は、テーブル作成時に iceberg_metadata_file_path (25.4+) または iceberg_metadata_table_uuid を使って参照先を固定してください。メタデータファイルの解決 を参照してください。

タイムトラベル

iceberg_timestamp_ms または iceberg_snapshot_id (いずれも 25.4+) を使用すると、過去時点のスナップショットを読み取れます。同じクエリで両方を設定しないでください。ID を選択する前に、system.iceberg_history (25.6+) でスナップショットの系統を確認してください。繰り返しのバッチロードについては、バッチ読み取りをスナップショットに制限する を参照してください。

Iceberg への書き込み

allow_insert_into_iceberg (25.7+、26.2 以降はベータ) に加え、INSERT 時の出力ファイルサイズとパーティション数を制御することもできます。 データレイクへの書き込みIceberg エンジンのリファレンス を参照してください。

Delta Lake

バージョン 25.6 以降、ClickHouse は Delta Lake Rust カーネル (allow_experimental_delta_kernel_rs、25.5+) を通じて、S3 および GCS 上の Delta Lake を読み取ります。Azure Blob Storage ではカーネルが無効になっているため、従来の reader を使用して deltaLakeAzure() を利用してください。カーネルを使用しない場合、パーティションプルーニング、変更データフィード、スナップショットバージョン の読み取りは利用できません。

Delta Kernel

allow_experimental_delta_kernel_rs は、パーティションプルーニング、変更データフィード、スナップショット バージョンの読み取りを利用するには有効にする必要があります。25.5 以降では、S3 と GCS でデフォルトで有効です。古いバージョンを使用している場合やトラブルシューティング時には、明示的に有効化してください。

読み取り設定

deletion vectors を持つテーブル (26.2+) では、読み取り時に行レベルのフィルタリングが適用されます。ClickHouse はこれを自動的に処理しますが、DV の多いテーブルでは、スキャン時にファイルごとの処理負荷が増えます。

Delta の変更データフィード

2 つの Delta スナップショット間で変更された行のみを読み取るには、delta_lake_snapshot_start_versiondelta_lake_snapshot_end_version (25.12+) を設定します。テーブルでは、アップストリームで変更データフィード (delta.enableChangeDataFeed) が有効になっている必要があります。開始バージョンと終了バージョンの両方をクエリ設定で指定してください。終了バージョンだけを指定するとエラーになります。
各回の読み込みが成功するたびに終了バージョンを保存し、次回の実行時にそれを開始バージョンとして渡します。結果には CDF のカラム (_change_type_commit_version_commit_timestamp) が含まれます。ターゲットテーブルに読み込む前に、これらを処理してください。一般的なスナップショットのパターンについては、バッチ読み取りをスナップショットにバインドするを参照してください。

Delta Lake への書き込み

allow_delta_lake_writes (25.9+) に加え、INSERT 時の出力ファイルサイズを制御できます。
書き込みには、S3 または GCS 上の Delta Kernel が必要です。例については、DeltaLake エンジン リファレンスを参照してください。

データレイククエリのデバッグ

遅いデータレイククエリや想定外の結果を返すクエリは、多くの場合、メタデータの読み取り、パーティションプルーニング、またはカタログへの接続に起因します。まずは以下のチェックを行い、必要に応じてフォーマット固有のメタデータログを使用してください。

カタログ接続を確認する

CREATE DATABASEDataLakeCatalog では認証情報は検証されません。カタログへの接続が切れていても、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を使用してください。

読み取られているファイルを確認する

Iceberg と Delta Lake では、読み取り時に毎回 仮想カラム (_path_file_size_time_etag) が公開されます。_path でグループ化すると、パーティションプルーニングが機能しているか、あるいはクエリが想定以上に多くのファイルをスキャンしているかを確認できます。隠しパーティション化を使用する Iceberg テーブルでは、別のパーティションカラムではなく、元のカラム (たとえば event_time) で絞り込んでください。

スキャン量を確認する

フィルターの追加や設定の調整の前後で、system.query_logread_rowsread_bytes を比較します。ReadBufferFromS3BytesCachedReadBufferReadFromCacheBytes などの ProfileEvents を見ると、オブジェクトストレージ由来のデータ量とローカル cache 由来のデータ量を確認できます。query_log と EXPLAIN の詳しい手順については、クエリ最適化 を参照してください。 ベンチマーク時には、cache ヒットによって実行ごとの差が見えにくくならないよう、enable_filesystem_cache を無効にしてください。

メタデータログ

ClickHouse には、メタデータレベルのデバッグ用システムテーブルが 3 つあります。ログの有効化はクエリ時のみにしてください。継続的な監視用途には適していません。 ログを有効にしてクエリを実行し、ログを flush してから、その query_id のエントリを確認します。
ClickHouse Cloud では、ログデータは各ノードにローカルです。レプリカ全体を通した状況を確認するには、clusterAllReplicas を使用してください。 Iceberg の詳細なログレベルでは、マニフェストリストとファイルのメタデータのキャッシュが無効になるため、同じテーブルに対する後続のクエリが遅くなります。詳細度を高くするのは、実際に調査しているときだけにしてください。Delta Lake の述語に関する問題については、カーネルがフィルターをプッシュダウンできない場合に即座に失敗させるため、delta_lake_throw_on_engine_predicate_error (25.8+) を有効にしてください。 カラムの詳細と詳細度オプションについては、iceberg_metadata_logdelta_lake_metadata_log のリファレンスページを参照してください。

次のステップ

最終更新日 2026年7月23日