一般的なマテリアライゼーション設定
サポートされているテーブルエンジン
注: materialized view では、すべての *MergeTree エンジンがサポートされています。
実験的にサポートされているテーブルエンジン
上記のいずれかのエンジンを使用して dbt から ClickHouse に接続する際に問題が発生した場合は、
こちらから issue を報告してください。
モデル設定に関する注意
settings は、CREATE TABLE/VIEW 型の DDL ステートメントで使用される SETTINGS
句を指し、一般に特定の ClickHouse テーブルエンジン固有の設定を意味します。新しい
query_settings は、モデルのマテリアライゼーションで使用される INSERT および DELETE クエリに SETTINGS 句を追加するためのものです (
増分マテリアライゼーションを含む) 。
ClickHouse には何百もの設定があり、どれが「テーブル」設定で、どれが「ユーザー」
設定なのかが必ずしも明確ではありません (ただし後者は、一般に
system.settings テーブルで確認できます) 。基本的にはデフォルト値の使用が推奨されており、これらのプロパティを使用する場合は
十分に調査と検証を行ってください。
カラム設定
注: 以下のカラム設定オプションを利用するには、モデルコントラクト が適用されている必要があります。
スキーマ設定の例
複雑な型の追加
data_type プロパティで指定した型と競合することがあります。これを回避するには、モデルの SQL で CAST() 関数を使用して、意図した型を明示的に定義することを推奨します。たとえば、次のようになります。
マテリアライゼーション: ビュー
dbt_project.yml) :
models/<model_name>.sql) :
マテリアライゼーション: テーブル
dbt_project.yml):
models/<model_name>.sql) :
データスキッピングインデックス
indexes 設定を使用すると、table マテリアライゼーションにデータスキッピングインデックスを追加できます:
プロジェクション
projections 設定を使用すると、table および distributed_table マテリアライゼーションにプロジェクションを追加できます。各プロジェクションエントリには、query キーまたは index キーのいずれか一方 (両方ではない) が必要です。
注: 分散テーブルでは、プロジェクションは分散プロキシテーブルではなく、_local テーブルに適用されます。
注: 同じプロジェクションエントリで query と index の両方を指定すると、コンパイル時エラーが発生します。
クエリプロジェクション
query を使用します。
索引プロジェクション
index は、_part_offset 仮想カラムを使用する軽量な索引プロジェクションのシンタックスシュガーです。ソート順には、単一のカラム名またはカラムのリストを指定します。
マテリアライゼーション: インクリメンタル
dbt_project.yml でのモデル定義:
models/<model_name>.sql の config ブロック:
設定
インクリメンタルモデルの戦略
dbt-clickhouse は、3種類のインクリメンタルモデル戦略をサポートしています。
デフォルト (レガシー) 戦略
Delete+Insert 戦略
delete+insert 戦略では、論理削除を使用して影響を受ける行を削除した後、新しい行を挿入します。テーブル全体をコピーしないため、「legacy」戦略よりも大幅に高いパフォーマンスを発揮します。プロファイルで use_lw_deletes: true を設定すると、delete+insert がデフォルトのインクリメンタル戦略になります。
この戦略の使用には、重要な注意点があります。
- 中間テーブルや一時テーブルを作成せず、影響を受けるテーブルを直接操作するため、操作中に 問題が発生した場合、インクリメンタルモデル内のデータが無効な状態になる可能性があります。
- ClickHouse 設定
allow_nondeterministic_mutationsが必要です。アダプターは可能な場合、自身の セッションでこの設定を自動的に有効にします。有効にできない場合 (たとえば、dbt ユーザーに対して読み取り専用に設定されている場合) 、動作は 戦略の選択方法によって異なります。デフォルト戦略に依存するモデルは通知なく legacy 戦略にフォールバックしますが、delete+insertまたはmicrobatchを明示的に設定したモデルは実行時に失敗し、 プロファイルのuse_lw_deletes: trueは接続時に失敗します。 - ごくまれに、非決定論的な
incremental_predicatesを使用すると、更新または削除される項目で競合状態が発生する可能性があります。 一貫した結果を得るには、インクリメンタル述語には、インクリメンタルマテリアライゼーション中に変更されないデータに対するサブクエリのみを含める必要があります。
Microbatch 戦略 (dbt-core >= 1.9 が必要)
microbatch は dbt-core 1.9 で導入された機能で、大規模な
時系列データの変換を効率的に処理できるよう設計されています。dbt-clickhouse では、既存の delete_insert
インクリメンタル戦略をベースに、event_time と
batch_size のモデル設定に基づいて、インクリメントをあらかじめ定義された時系列バッチに分割して処理します。
大規模な変換の処理に加えて、microbatch には次のような利点があります。
- 失敗したバッチを再処理する。
- 並列バッチ実行を自動検出する。
- 履歴データの補完で複雑な条件分岐ロジックが不要になる。
利用可能な Microbatch 設定
Append 戦略
inserts_only 設定の代わりとなるものです。この方式では、既存のリレーションに新しい行を単純に追加します。
そのため、重複した行は排除されず、一時テーブルや中間テーブルも作成されません。データ内で重複が許容されている場合、またはインクリメンタルクエリの WHERE 句/フィルタで除外される場合は、これが最も高速な方式です。
insert_overwrite 戦略 (実験的)
[IMPORTANT]
現在、insert_overwrite 戦略は分散マテリアライゼーションでは完全には機能しません。
次の手順を実行します。
- incremental model の リレーション と同じ structure を持つ staging (一時) table を作成します:
CREATE TABLE <staging> AS <target>. - 新しいレコード (
SELECTによって生成されたもの) のみを staging table に insert します。 - 新しいパーティション (staging table に存在するもの) のみをターゲットテーブルに置き換えます。
- テーブル全体をコピーしないため、デフォルトの戦略より高速です。
INSERT操作が正常に完了するまで元のテーブルを変更しないため、他の戦略より安全です。途中で障害が発生した場合でも、元のテーブルは変更されません。- データエンジニアリングにおける「パーティション不変性」のベストプラクティスを実現します。これにより、増分処理、並列データ処理、ロールバックなどが簡単になります。
partition_by を設定する必要があります。model config のそのほかの戦略固有の parameter はすべて無視されます。
マテリアライゼーション: materialized_view
materialized_view マテリアライゼーションは、挿入トリガーとして機能する ClickHouse の materialized view を作成し、ソーステーブルからターゲットテーブルへ新しい行を自動的に変換して挿入します。これは、dbt-clickhouse で利用できるマテリアライゼーションの中でも特に強力なものの 1 つです。
このマテリアライゼーションは内容が多岐にわたるため、専用のページを用意しています。完全なドキュメントについては、**Materialized Views ガイド**をご覧ください。
マテリアライゼーション: Dictionary (実験的)
dbt run のたびに、CREATE OR REPLACE DICTIONARY を使用してDictionaryが現在のモデル定義に置き換えられます。
設定
ClickHouse ソースを使用する例
HTTPログソースを使用する例
source_type='http' (または table オプション) を使用する場合、モデルのSQLはログソースとして使用されません。ただし、dbtでは引き続きボディが必要なため、select 1 をプレースホルダーとして使用してください。
マテリアライゼーション: distributed_table (実験的)
- 適切な構造を取得するためのSQLクエリを使って一時ビューを作成する
- ビューに基づいて空のローカルテーブルを作成する
- ローカルテーブルに基づいて分散テーブルを作成する。
- データは分散テーブルに挿入されるため、重複することなく各分片に分散される。
- dbt-clickhouse のクエリには現在、設定
insert_distributed_sync = 1が自動的に含まれており、これにより 下流のインクリメンタル マテリアライゼーション操作が正しく実行されることが保証されます。そのため、一部の分散テーブルへの挿入が 想定より遅くなる可能性があります。
分散テーブルモデルの例
生成された移行
設定
materialization: distributed_incremental (実験的)
- The Append Strategy は、データを分散テーブルに insert するだけです。
- The Delete+Insert Strategy では、各分片上のすべてのデータを処理するために分散一時テーブルを作成します。
- The Default (Legacy) Strategy では、同じ理由で分散一時テーブルと中間テーブルを作成します。
Distributed incrementalモデルの例
生成された移行
スナップショット
snapshots/<model_name>.sql の設定ブロック:
コントラクトと制約
CHECK 制約 のみ です。主キー、外部キー、一意制約、および
カラムレベルの CHECK 制約はサポートされていません。
(主キー / ORDER BY キーについては、ClickHouse のドキュメントを参照してください。)