ClickHouse 설정

dbt-clickhouse 어댑터에서 모델을 view, table, incremental로 materialize하는 방법을 다루는 페이지예요. ClickHouse 특유의 engine, order_by, partition_by, unique_key 같은 설정을 모델에 지정해서 생성되는 테이블을 세밀하게 제어할 수 있어요.

출처: 문서

본문

View materialization

dbt 모델은 ClickHouse view로 생성할 수 있는데, 다음 문법으로 구성해요.

Project YAML 파일

dbt_project.yml

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

SQL 파일 config

models/<model_name>.sql

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

Table materialization

dbt 모델은 ClickHouse table로 생성할 수 있는데, 다음 문법으로 구성해요.

Project YAML 파일

dbt_project.yml

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

SQL 파일 config

models/<model_name>.sql

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

Table configuration

Option	설명	필수 여부?
`materialized`	모델이 ClickHouse에 어떻게 materialize되는지를 나타내요. table 모델을 만들려면 `table`이어야 해요.	필수
`engine`	테이블을 만들 때 사용할 테이블 엔진이에요. 아래의 지원 엔진 목록을 참고하세요.	선택 (기본값: `MergeTree()`)
`order_by`	컬럼 이름 또는 임의 표현식의 튜플이에요. 데이터를 더 빠르게 찾는 데 도움이 되는 작은 희소 인덱스를 만들 수 있어요.	선택 (기본값: `tuple()`)
`partition_by`	파티션은 특정 기준에 따라 테이블의 레코드를 논리적으로 결합한 것이에요. 파티션 키는 테이블 컬럼의 어떤 표현식이든 될 수 있어요.	선택

전체 구성 옵션 목록은 ClickHouse documentation을 참고하세요.

Incremental materialization

Table 모델은 매번 dbt 실행마다 재구성돼요. 결과 집합이 크거나 변환이 복잡하면 이는 비현실적이고 매우 비쌀 수 있어요. 이 문제를 해결하고 빌드 시간을 줄이기 위해, dbt 모델을 incremental ClickHouse 테이블로 생성할 수 있어요. 구성은 다음 문법을 사용해요.

Project 파일

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 ]

SQL 파일 config

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 ],
      ...
    ]
) }}

Incremental table configuration

Option	설명	필수 여부?
`materialized`	모델이 ClickHouse에 어떻게 materialize되는지를 나타내요. table 모델을 만들려면 `table`이어야 해요.	필수
`unique_key`	행을 고유하게 식별하는 컬럼 이름의 튜플이에요. 유니크 제약 조건에 대한 자세한 내용은 여기를 참고하세요.	필수. 제공하지 않으면 수정된 행이 incremental 테이블에 두 번 추가돼요.
`engine`	테이블을 만들 때 사용할 테이블 엔진이에요. 아래의 지원 엔진 목록을 참고하세요.	선택 (기본값: `MergeTree()`)
`order_by`	컬럼 이름 또는 임의 표현식의 튜플이에요. 데이터를 더 빠르게 찾는 데 도움이 되는 작은 희소 인덱스를 만들 수 있어요.	선택 (기본값: `tuple()`)
`partition_by`	파티션은 특정 기준에 따라 테이블의 레코드를 논리적으로 결합한 것이에요. 파티션 키는 테이블 컬럼의 어떤 표현식이든 될 수 있어요.	선택
`inserts_only`	(비권장, `append` materialization 전략 참고) True면 중간 테이블을 만들지 않고 타깃 incremental 테이블에 직접 incremental 업데이트를 삽입해요.	선택 (기본값: `False`)
`incremental_strategy`	incremental materialization에 사용할 전략이에요. `delete+insert`, `append`, `insert_overwrite`(실험적)를 지원해요. 전략에 대한 추가 정보는 여기를 참고하세요.	선택 (기본값: 'default')
`incremental_predicates`	`delete+insert` materialization에 적용할 incremental predicate 절이에요.	선택

전체 구성 옵션 목록은 ClickHouse documentation을 참고하세요.

Snapshot

dbt snapshot은 가변(mutable) 모델의 변경 사항을 시간에 따라 기록할 수 있게 해줘요. 이를 통해 모델의 이전 상태를 "과거로 돌아가" 볼 수 있는 시점(point-in-time) 쿼리가 가능해져요. 이 기능은 ClickHouse 커넥터에서 지원되며 다음 문법으로 구성돼요.

(dbt v1.9 이상 적용)

snapshots/<model_name>.sql

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

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

더 알아보기 (Learn more)

dbt-clickhouse 어댑터는 테스트, snapshot, 헬퍼 매크로 등 대부분의 dbt 네이티브 기능을 지원해요. 지원되는 기능과 모범 사례의 전체 개요는 ClickHouse documentation을 참고하세요.
incremental 모델 유니크 키에 대한 자세한 설명은 incremental-models 문서를 참고하세요.