머티리얼라이즈

이 섹션에서는 실험적 기능을 포함해 dbt-clickhouse에서 제공하는 모든 머티리얼라이즈를 설명합니다.

다음 표는 사용 가능한 일부 머티리얼라이즈에서 공통으로 사용되는 구성을 보여줍니다. 일반적인 dbt 모델 구성에 대한 자세한 내용은 dbt documentation을 참조하십시오.

참고: materialized view의 경우, 모든 *MergeTree 엔진이 지원됩니다.

위 엔진 중 하나로 dbt에서 ClickHouse에 연결하는 데 문제가 발생하면 여기에 이슈를 보고해 주십시오.

ClickHouse에는 여러 유형/수준의 "설정"이 있습니다. 위의 모델 구성에서는 이 중 두 가지를 구성할 수 있습니다. settings는 CREATE TABLE/VIEW 유형의 DDL SQL 문에서 사용되는 SETTINGS 절을 의미하며, 일반적으로 특정 ClickHouse 테이블 엔진에 특화된 설정입니다. 새로운 query_settings는 모델 머티리얼라이즈에 사용되는 INSERT 및 DELETE 쿼리(증분 머티리얼라이즈 포함)에 SETTINGS 절을 추가하는 데 사용됩니다. ClickHouse에는 수백 개의 설정이 있으며, 어떤 것이 "table" 설정이고 어떤 것이 "user" 설정인지 항상 명확하지는 않습니다(다만 후자는 일반적으로 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'
           }
       ]
) }}

_part_offset 가상 컬럼을 사용하는 경량 인덱스 프로젝션의 구문 단축형으로 index를 사용합니다. 정렬 기준으로 단일 컬럼명 또는 컬럼명 목록을 전달합니다:

{{ 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를 실행할 때마다 다시 생성됩니다. 이는 결과 집합(result set)이 크거나 변환이 복잡한 경우 현실적으로 어렵고 비용도 매우 많이 들 수 있습니다. 이 문제를 해결하고 빌드 시간을 줄이기 위해 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(
    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는 비동기식 "뮤테이션" 형태로만 업데이트와 삭제를 제한적으로 지원했습니다. 예상되는 dbt 동작을 구현하기 위해, dbt-clickhouse는 기본적으로 영향을 받지 않은(삭제되지 않았고 변경되지 않은) 모든 "기존" 레코드와 새로 추가되거나 업데이트된 레코드를 포함하는 새 임시 테이블을 생성한 다음, 이 임시 테이블을 기존 증분 모델 릴레이션과 스왑하거나 EXCHANGE합니다. 이 전략은 작업이 완료되기 전에 문제가 발생하더라도 원래 릴레이션을 보존할 수 있는 유일한 전략입니다. 하지만 원본 테이블 전체를 복사해야 하므로, 실행 비용이 상당히 크고 속도도 느릴 수 있습니다.

delete+insert 전략은 경량한 삭제를 사용해 영향을 받는 행을 제거한 후 새 행을 삽입합니다. 전체 테이블을 복사하지 않으므로 "레거시" 전략보다 성능이 훨씬 뛰어납니다. 프로필에서 use_lw_deletes: true를 설정하면 delete+insert가 기본 incremental 전략으로 지정됩니다.

이 전략을 사용할 때는 다음과 같은 중요한 주의 사항이 있습니다.

• 중간 또는 임시 테이블을 생성하지 않고 영향을 받는 테이블을 직접 처리하므로, 작업 중 문제가 발생하면 incremental 모델의 데이터가 유효하지 않은 상태가 될 가능성이 높습니다.
• ClickHouse 설정 allow_nondeterministic_mutations가 필요합니다. 어댑터는 가능하면 자체 세션에서 이를 자동으로 활성화합니다. 활성화할 수 없는 경우(예: dbt 사용자가 읽기 전용인 경우) 동작은 전략을 선택한 방식에 따라 달라집니다. 기본 전략을 사용하는 모델은 자동으로 레거시 전략으로 폴백되며, delete+insert 또는 microbatch를 명시적으로 설정한 모델은 런타임에 실패하고, 프로필의 use_lw_deletes: true는 연결 시 실패합니다.
• 매우 드문 경우, 비결정적인 incremental_predicates를 사용하면 업데이트되거나 삭제되는 항목에 race condition이 발생할 수 있습니다. 일관된 결과를 보장하려면 incremental 프레디케이트에는 incremental 머티리얼라이즈 중 수정되지 않을 데이터에 대한 하위 쿼리만 포함해야 합니다.

증분 전략 microbatch는 dbt-core 1.9부터 지원되는 기능으로, 대규모 시계열 데이터(time-series data) 변환을 효율적으로 처리하도록 설계되었습니다. dbt-clickhouse에서는 기존 delete_insert 증분 전략을 기반으로 하며, event_time 및 batch_size 모델 구성에 따라 증분 처리를 미리 정의된 시계열 배치로 분할합니다.

대규모 변환 처리 외에도, microbatch는 다음과 같은 기능을 제공합니다:

• 실패한 배치를 재처리할 수 있습니다.
• 병렬 배치 실행을 자동으로 감지합니다.
• 백필 시 복잡한 조건부 로직이 필요하지 않습니다.

microbatch 사용법에 대한 자세한 내용은 공식 문서를 참조하십시오.

이 전략은 이전 버전의 dbt-clickhouse에서 inserts_only 설정을 대체합니다. 이 방식은 기존 릴레이션에 새 행을 단순히 추가만 합니다. 따라서 중복 행은 제거되지 않으며, 임시 테이블이나 중간 테이블도 사용하지 않습니다. 데이터에서 중복이 허용되거나 증분 쿼리의 WHERE 절/필터로 제외되는 경우 가장 빠른 방식입니다.

[IMPORTANT] 현재 insert_overwrite 전략은 분산 머티리얼라이즈에서 완전히 동작하지 않습니다.

다음 단계를 수행합니다:

1. 증분 모델 릴레이션과 동일한 구조를 가진 스테이징(임시) 테이블을 생성합니다: CREATE TABLE <staging> AS <target>.
2. 새 레코드만(SELECT로 생성됨) 스테이징 테이블에 삽입합니다.
3. 새 파티션만(스테이징 테이블에 있는 파티션) 대상 테이블에 대체합니다.

이 접근 방식에는 다음과 같은 장점이 있습니다:

• 전체 테이블을 복사하지 않으므로 기본 전략보다 더 빠릅니다.
• INSERT 작업이 성공적으로 완료될 때까지 원본 테이블을 수정하지 않으므로 다른 전략보다 더 안전합니다: 중간에 실패하더라도 원본 테이블은 수정되지 않습니다.
• 데이터 엔지니어링 모범 사례인 "파티션 불변성"을 구현합니다. 이를 통해 증분 및 병렬 데이터 처리, 롤백 등이 단순해집니다.

이 전략을 사용하려면 모델 구성에서 partition_by를 설정해야 합니다. 모델 구성의 다른 모든 전략별 매개변수는 무시됩니다.

materialized_view 머티리얼라이즈는 삽입 트리거 역할을 하는 ClickHouse materialized view를 생성하며, 원본 테이블의 새 행을 자동으로 변환해 대상 테이블에 삽입합니다. 이는 dbt-clickhouse에서 사용할 수 있는 가장 강력한 머티리얼라이즈 중 하나입니다.

이 머티리얼라이즈는 내용이 방대하므로 전용 페이지에서 별도로 다룹니다. 전체 문서는 **Materialized Views 가이드**를 참조하십시오.

dbt 모델은 ClickHouse 딕셔너리로 생성할 수 있습니다. dbt run을 실행할 때마다 CREATE OR REPLACE DICTIONARY를 사용하여 현재 모델 정의로 딕셔너리를 대체합니다.

모델의 SQL이 딕셔너리 소스 쿼리로 사용됩니다:

{{ 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 딕셔너리를 포함한 더 많은 예시는 딕셔너리 테스트를 참조하십시오.

분산 테이블은 다음 단계에 따라 생성됩니다:

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. _Append 전략_은 데이터를 분산 테이블에 그대로 삽입합니다.
2. Delete+Insert 전략은 모든 세그먼트의 모든 데이터를 처리할 수 있도록 분산 임시 테이블을 생성합니다.
3. _Default (Legacy) 전략_은 같은 이유로 분산 임시 테이블과 중간 테이블을 생성합니다.

분산 테이블은 데이터를 저장하지 않으므로 교체되는 것은 세그먼트 테이블뿐입니다. 분산 테이블은 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 스냅샷은 시간의 흐름에 따라 변경되는 가변 모델의 변경 이력을 기록할 수 있도록 합니다. 이를 통해 모델에 대해 특정 시점 기준의 쿼리를 수행할 수 있으며, 분석가는 모델의 이전 상태를 "과거 시점으로 돌아가" 확인할 수 있습니다. 이 기능은 ClickHouse Connector에서 지원되며, 다음 구문을 사용해 구성합니다:

snapshots/<model_name>.sql의 설정 블록:

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

구성에 대한 자세한 내용은 snapshot 구성 참고 페이지를 참조하세요.

정확히 일치하는 컬럼 유형 계약만 지원됩니다. 예를 들어, UInt32 컬럼 유형 계약은 모델이 UInt64 또는 다른 정수 유형을 반환하는 경우 실패합니다. ClickHouse는 테이블/모델 전체에 대한 CHECK 제약 조건 만 지원합니다. 프라이머리 키, 외래 키, 고유 제약 조건 및 컬럼 수준의 CHECK 제약 조건은 지원되지 않습니다. (프라이머리 키/ORDER BY 키는 ClickHouse 문서를 참조하십시오.)