一般的なマテリアライゼーション設定
サポートされているテーブルエンジン
注: 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 マテリアライゼーションにプロジェクションを追加できます。
_local テーブルに適用されます。
マテリアライゼーション: インクリメンタル
dbt_project.yml でのモデル定義:
models/<model_name>.sql の config ブロック:
設定
インクリメンタルモデルの戦略
dbt-clickhouse は、3種類のインクリメンタルモデル戦略をサポートしています。
デフォルト (レガシー) 戦略
Delete+Insert 戦略
delete+insert
は論理削除を利用して、
「legacy」戦略よりも大幅に高い性能を発揮するインクリメンタルマテリアライゼーションを実装します。ただし、この戦略を使用する際には重要な
注意点があります:
- 論理削除を使用するには、設定
allow_experimental_lightweight_delete=1を使って ClickHouse server で有効化するか、 profile でuse_lw_deletes=trueを設定する必要があります (これにより dbt のセッションでその設定が有効になります) - 論理削除は現在では本番利用可能ですが、23.3 より前の ClickHouse バージョンでは性能面やその他の問題が 発生する可能性があります。
- この戦略は、影響を受ける table/リレーション に対して中間テーブルや一時テーブルを作成せずに直接動作するため、処理中に問題が発生した場合、 インクリメンタル model の データが無効な状態になる可能性があります
- 論理削除を使用する場合、dbt-clickhouse は設定
allow_nondeterministic_mutationsを有効にします。ごく まれに、非決定論的な incremental_predicates を使用すると、 更新または削除された項目 (および ClickHouse logs 内の関連する log messages) で race condition が発生する可能性があります。 一貫した結果を確実に得るには、 incremental predicates には、インクリメンタル materialization 中に変更されないデータに対するサブクエリだけを含めるようにしてください。
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 (実験的)
マテリアライゼーション: 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 のドキュメントを参照してください。)