マテリアライゼーション

このセクションでは、dbt-clickhouse で利用可能なすべてのマテリアライゼーション (実験的な機能を含む) について説明します。

次の表は、利用可能なマテリアライゼーションの一部で共通して使用される設定を示しています。一般的な dbt モデル設定の詳細については、dbt documentationを参照してください。

注: materialized view では、すべての *MergeTree エンジンがサポートされています。

上記のいずれかのエンジンを使用して dbt から ClickHouse に接続する際に問題が発生した場合は、 こちらから issue を報告してください。

ClickHouse には、「設定」にいくつかの種類やレベルがあります。上記のモデル構成では、そのうち 2 種類を 設定できます。settings は、CREATE TABLE/VIEW 型の DDL ステートメントで使用される SETTINGS 句を指し、一般に特定の ClickHouse テーブルエンジン固有の設定を意味します。新しい query_settings は、モデルのマテリアライゼーションで使用される INSERT および DELETE クエリに SETTINGS 句を追加するためのものです ( 増分マテリアライゼーションを含む) 。 ClickHouse には何百もの設定があり、どれが「テーブル」設定で、どれが「ユーザー」 設定なのかが必ずしも明確ではありません (ただし後者は、一般に system.settings テーブルで確認できます) 。基本的にはデフォルト値の使用が推奨されており、これらのプロパティを使用する場合は 十分に調査と検証を行ってください。

注: 以下のカラム設定オプションを利用するには、モデルコントラクト が適用されている必要があります。

models:
  - name: table_column_configs
    description: 'Testing column-level configurations'
    config:
      contract:
        enforced: true
    columns:
      - name: ts
        data_type: timestamp
        codec: ZSTD
      - name: x
        data_type: UInt8
        ttl: ts + INTERVAL 1 DAY

dbt は、モデルの作成に使用される SQL を分析して、各カラムのデータ型を自動的に判定します。ただし、場合によってはこの処理でデータ型を正確に判定できず、contract の data_type プロパティで指定した型と競合することがあります。これを回避するには、モデルの SQL で CAST() 関数を使用して、意図した型を明示的に定義することを推奨します。たとえば、次のようになります。

{{
    config(
        materialized="materialized_view",
        engine="AggregatingMergeTree",
        order_by=["event_type"],
    )
}}

select
  -- event_type は String として推論される場合があるが、LowCardinality(String) を使用したい場合がある:
  CAST(event_type, 'LowCardinality(String)') as event_type,
  -- countState() は `AggregateFunction(count)` として推論される場合があるが、使用する引数の型を変更したい場合がある:
  CAST(countState(), 'AggregateFunction(count, UInt32)') as response_count, 
  -- maxSimpleState() は `SimpleAggregateFunction(max, String)` として推論される場合があるが、使用する引数の型も変更したい場合がある:
  CAST(maxSimpleState(event_type), 'SimpleAggregateFunction(max, LowCardinality(String))') as max_event_type
from {{ ref('user_events') }}
group by event_type

dbtのモデルは、ClickHouseビューとして作成でき、 次の構文で設定できます。

プロジェクトファイル (dbt_project.yml) :

models:
  <resource-path>:
    +materialized: view

または、設定ブロック (models/<model_name>.sql) :

{{ config(materialized = "view") }}

dbtモデルは ClickHouseテーブル として作成でき、 次の構文で設定できます。

プロジェクトファイル (dbt_project.yml):

models:
  <resource-path>:
    +materialized: table
    +order_by: [ <column-name>, ... ]
    +engine: <engine-type>
    +partition_by: [ <column-name>, ... ]

または config ブロック (models/<model_name>.sql) :

{{ config(
    materialized = "table",
    engine = "<engine-type>",
    order_by = [ "<column-name>", ... ],
    partition_by = [ "<column-name>", ... ],
      ...
    ]
) }}

indexes 設定を使用すると、table マテリアライゼーションにデータスキッピングインデックスを追加できます：

{{ config(
        materialized='table',
        indexes=[{
          'name': 'your_index_name',
          'definition': 'your_column TYPE minmax GRANULARITY 2'
        }]
) }}

projections 設定を使用すると、table および distributed_table マテリアライゼーションにプロジェクションを追加できます。各プロジェクションエントリには、query キーまたは index キーのいずれか一方 (両方ではない) が必要です。

注: 分散テーブルでは、プロジェクションは分散プロキシテーブルではなく、_local テーブルに適用されます。 注: 同じプロジェクションエントリで query と index の両方を指定すると、コンパイル時エラーが発生します。

完全なプロジェクションクエリを定義するには、query を使用します。

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'your_projection_name',
               'query': 'SELECT department, avg(age) AS avg_age GROUP BY department'
           }
       ]
) }}

index は、_part_offset 仮想カラムを使用する軽量な索引プロジェクションのシンタックスシュガーです。ソート順には、単一のカラム名またはカラムのリストを指定します。

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'proj_by_age',
               'index': 'age'
           }
       ]
) }}

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'proj_by_dept_age',
               'index': ['department', 'age']
           }
       ]
) }}

dbt-clickhouse は、バージョンに適した DDL を自動的に生成します。

テーブルモデルは、dbt の実行のたびに再構築されます。これは、結果セットが大きい場合や変換が複雑な場合には現実的ではなく、コストが非常に高くなる可能性があります。この課題に対処し、ビルド時間を短縮するために、dbt モデルは インクリメンタル な ClickHouse テーブルとして作成でき、次の構文で設定します。

dbt_project.yml でのモデル定義:

models:
  <resource-path>:
    +materialized: incremental
    +order_by: [ <column-name>, ... ]
    +engine: <engine-type>
    +partition_by: [ <column-name>, ... ]
    +unique_key: [ <column-name>, ... ]
    +inserts_only: [ True|False ]

または、models/<model_name>.sql の config ブロック:

{{ config(
    materialized = "incremental",
    engine = "<engine-type>",
    order_by = [ "<column-name>", ... ],
    partition_by = [ "<column-name>", ... ],
    unique_key = [ "<column-name>", ... ],
    inserts_only = [ True|False ],
      ...
    ]
) }}

このマテリアライゼーションタイプ固有の設定を以下に示します。

dbt-clickhouse は、3種類のインクリメンタルモデル戦略をサポートしています。

ClickHouse では従来、更新と削除のサポートは非同期の「mutation」による限定的なものしかありませんでした。 期待される dbt の動作を再現するため、 dbt-clickhouse はデフォルトで、影響を受けていない (削除も変更もされていない) 既存の レコードをすべて含み、さらに新規または更新されたレコードを加えた新しい一時テーブルを作成し、 その後、この一時テーブルを既存の インクリメンタル model リレーション とスワップまたは EXCHANGE します。これは、処理の完了前に何らかの 問題が発生した場合でも元の リレーション を保持できる唯一の戦略です。ただし、元のテーブル全体をコピーする必要があるため、 実行コストが高く、処理にも時間がかかる可能性があります。

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 で導入された機能で、大規模な 時系列データの変換を効率的に処理できるよう設計されています。dbt-clickhouse では、既存の delete_insert インクリメンタル戦略をベースに、event_time と batch_size のモデル設定に基づいて、インクリメントをあらかじめ定義された時系列バッチに分割して処理します。

大規模な変換の処理に加えて、microbatch には次のような利点があります。

• 失敗したバッチを再処理する。
• 並列バッチ実行を自動検出する。
• 履歴データの補完で複雑な条件分岐ロジックが不要になる。

microbatch の詳細な使い方については、公式ドキュメントを参照してください。

この戦略は、以前のバージョンの dbt-clickhouse における inserts_only 設定の代わりとなるものです。この方式では、既存のリレーションに新しい行を単純に追加します。 そのため、重複した行は排除されず、一時テーブルや中間テーブルも作成されません。データ内で重複が許容されている場合、またはインクリメンタルクエリの WHERE 句/フィルタで除外される場合は、これが最も高速な方式です。

[IMPORTANT] 現在、insert_overwrite 戦略は分散マテリアライゼーションでは完全には機能しません。

次の手順を実行します。

1. incremental model の リレーション と同じ structure を持つ staging (一時) table を作成します: CREATE TABLE <staging> AS <target>.
2. 新しいレコード (SELECT によって生成されたもの) のみを staging table に insert します。
3. 新しいパーティション (staging table に存在するもの) のみをターゲットテーブルに置き換えます。

このアプローチには、次の利点があります。

• テーブル全体をコピーしないため、デフォルトの戦略より高速です。
• INSERT 操作が正常に完了するまで元のテーブルを変更しないため、他の戦略より安全です。途中で障害が発生した場合でも、元のテーブルは変更されません。
• データエンジニアリングにおける「パーティション不変性」のベストプラクティスを実現します。これにより、増分処理、並列データ処理、ロールバックなどが簡単になります。

この戦略を使用するには、model configuration で partition_by を設定する必要があります。model config のそのほかの戦略固有の parameter はすべて無視されます。

materialized_view マテリアライゼーションは、挿入トリガーとして機能する ClickHouse の materialized view を作成し、ソーステーブルからターゲットテーブルへ新しい行を自動的に変換して挿入します。これは、dbt-clickhouse で利用できるマテリアライゼーションの中でも特に強力なものの 1 つです。

このマテリアライゼーションは内容が多岐にわたるため、専用のページを用意しています。完全なドキュメントについては、**Materialized Views ガイド**をご覧ください。

dbtモデルは、ClickHouse のDictionaryとして作成できます。dbt run のたびに、CREATE OR REPLACE DICTIONARY を使用してDictionaryが現在のモデル定義に置き換えられます。

モデルの SQL が Dictionary ソースのクエリになります。

{{ config(
       materialized='dictionary',
       fields=[
           ('id', 'UInt64'),
           ('name', 'String'),
       ],
       primary_key='id',
       layout='HASHED()',
       lifetime='MIN 0 MAX 300'
) }}

select id, name from {{ source('raw', 'people') }}

source_type='http' (または table オプション) を使用する場合、モデルのSQLはログソースとして使用されません。ただし、dbtでは引き続きボディが必要なため、select 1 をプレースホルダーとして使用してください。

{{ config(
       materialized='dictionary',
       fields=[
           ('LocationID', 'UInt16 DEFAULT 0'),
           ('Borough', 'String'),
           ('Zone', 'String'),
       ],
       primary_key='LocationID',
       layout='HASHED()',
       lifetime='MIN 0 MAX 0',
       source_type='http',
       url='https://datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi/taxi_zone_lookup.csv',
       format='CSVWithNames'
) }}

select 1

range および direct Dictionary を含むその他の例については、dictionary テストを参照してください。

分散テーブルは、次の手順で作成されます:

1. 適切な構造を取得するためのSQLクエリを使って一時ビューを作成する
2. ビューに基づいて空のローカルテーブルを作成する
3. ローカルテーブルに基づいて分散テーブルを作成する。
4. データは分散テーブルに挿入されるため、重複することなく各分片に分散される。

注:

• dbt-clickhouse のクエリには現在、設定 insert_distributed_sync = 1 が自動的に含まれており、これにより 下流のインクリメンタル マテリアライゼーション操作が正しく実行されることが保証されます。そのため、一部の分散テーブルへの挿入が 想定より遅くなる可能性があります。

{{
    config(
        materialized='distributed_table',
        order_by='id, created_at',
        sharding_key='cityHash64(id)',
        engine='ReplacingMergeTree'
    )
}}

select id, created_at, item
from {{ source('db', 'table') }}

CREATE TABLE db.table_local on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = ReplacingMergeTree
    ORDER BY (id, created_at);

CREATE TABLE db.table on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id));

このマテリアライゼーション種別に固有の設定を以下に示します。

分散テーブルと同じ考え方に基づく増分モデルですが、主な難しさは、すべての増分 戦略を正しく処理することにあります。

1. The Append Strategy は、データを分散テーブルに insert するだけです。
2. The Delete+Insert Strategy では、各分片上のすべてのデータを処理するために分散一時テーブルを作成します。
3. The Default (Legacy) Strategy では、同じ理由で分散一時テーブルと中間テーブルを作成します。

分散テーブル自体はデータを保持しないため、置き換えられるのは分片テーブルのみです。 分散テーブルが再読み込みされるのは、full_refresh モードが有効な場合、またはテーブル構造が変更された可能性がある場合のみです。

{{
    config(
        materialized='distributed_incremental',
        engine='MergeTree',
        incremental_strategy='append',
        unique_key='id,created_at'
    )
}}

select id, created_at, item
from {{ source('db', 'table') }}

CREATE TABLE db.table_local on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = MergeTree;

CREATE TABLE db.table on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id));

dbt の snapshot を使用すると、変更可能なモデルに加えられた変更を時系列で記録できます。これにより、モデルに対して特定時点の クエリを実行できるようになり、アナリストはモデルの過去の状態を「さかのぼって」確認できます。この機能は ClickHouse コネクタでサポートされており、次の構文で設定します。

snapshots/<model_name>.sql の設定ブロック:

{{
   config(
     schema = "<schema-name>",
     unique_key = "<column-name>",
     strategy = "<strategy>",
     updated_at = "<updated-at-column-name>",
   )
}}

設定について詳しくは、スナップショット設定のリファレンスページを参照してください。

サポートされるのは、完全に一致するカラム型のコントラクトのみです。たとえば、UInt32 のカラム型を持つコントラクトでは、モデルが UInt64 やその他の整数型を返すと失敗します。 また、ClickHouse でサポートされるのは、テーブル/モデル全体に対する CHECK 制約 のみ です。主キー、外部キー、一意制約、および カラムレベルの CHECK 制約はサポートされていません。 (主キー / ORDER BY キーについては、ClickHouse のドキュメントを参照してください。)