일반 머티리얼라이즈 구성
다음 표는 사용 가능한 일부 머티리얼라이즈에서 공통으로 사용되는 구성을 보여줍니다. 일반적인 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 테이블에서 확인할 수 있습니다). 일반적으로는 기본값 사용을 권장하며, 이러한 속성을 사용할 때는
충분히 검토하고 테스트해야 합니다.
컬럼 구성
참고: 아래 컬럼 구성 옵션을 사용하려면 모델 계약이 적용되어 있어야 합니다.
스키마 구성 예시
복합 타입 추가
dbt는 모델을 생성하는 데 사용된 SQL을 분석해 각 컬럼의 데이터 타입을 자동으로 결정합니다. 하지만 경우에 따라 이 과정에서 데이터 타입을 정확히 판별하지 못해 계약의data_type 속성에 지정된 타입과 충돌이 발생할 수 있습니다. 이를 방지하려면 모델 SQL에서 CAST() 함수를 사용해 원하는 타입을 명시적으로 정의하는 것이 좋습니다. 예시는 다음과 같습니다:
머티리얼라이즈: 뷰
dbt 모델은 ClickHouse 뷰로 생성할 수 있으며 다음 구문으로 구성할 수 있습니다: 프로젝트 파일 (dbt_project.yml):
models/<model_name>.sql):
머티리얼라이즈: 테이블
dbt 모델은 ClickHouse 테이블로 생성할 수 있으며 다음 구문으로 구성할 수 있습니다: 프로젝트 파일 (dbt_project.yml):
models/<model_name>.sql):
데이터 스키핑 인덱스
indexes 구성을 사용해 table 머티리얼라이즈에 데이터 스키핑 인덱스를 추가할 수 있습니다.
프로젝션
projections 구성을 사용하면 table 및 distributed_table 머티리얼라이즈에 프로젝션을 추가할 수 있습니다. 각 프로젝션 항목에는 query 또는 index 키 중 하나만 필요합니다(둘 다 지정할 수 없음).
참고: 분산 테이블에서는 프로젝션이 분산 프록시 테이블이 아니라 _local 테이블에 적용됩니다.
참고: 동일한 프로젝션 항목에 query와 index를 모두 지정하면 컴파일 시간 오류가 발생합니다.
쿼리 프로젝션
query를 사용하여 전체 프로젝션 쿼리를 정의합니다:
인덱스 프로젝션
_part_offset 가상 컬럼을 사용하는 경량 인덱스 프로젝션의 구문 단축형으로 index를 사용합니다. 정렬 기준으로 단일 컬럼명 또는 컬럼명 목록을 전달합니다:
머티리얼라이즈: incremental
테이블 모델은 dbt를 실행할 때마다 다시 생성됩니다. 이는 결과 집합(result set)이 크거나 변환이 복잡한 경우 현실적으로 어렵고 비용도 매우 많이 들 수 있습니다. 이 문제를 해결하고 빌드 시간을 줄이기 위해 dbt 모델을 증분 ClickHouse 테이블로 생성할 수 있으며, 다음 구문으로 구성합니다:dbt_project.yml의 모델 정의:
models/<model_name>.sql의 구성 블록:
구성
이 머티리얼라이즈 유형에만 해당하는 구성은 아래와 같습니다:증분 모델 전략
dbt-clickhouse는 다음과 같은 증분 모델 전략을 지원합니다.
기본(레거시) 전략
과거 ClickHouse는 비동기식 “뮤테이션” 형태로만 업데이트와 삭제를 제한적으로 지원했습니다. 예상되는 dbt 동작을 구현하기 위해, dbt-clickhouse는 기본적으로 영향을 받지 않은(삭제되지 않았고 변경되지 않은) 모든 “기존” 레코드와 새로 추가되거나 업데이트된 레코드를 포함하는 새 임시 테이블을 생성한 다음, 이 임시 테이블을 기존 증분 모델 릴레이션과 스왑하거나 EXCHANGE합니다. 이 전략은 작업이 완료되기 전에 문제가 발생하더라도 원래 릴레이션을 보존할 수 있는 유일한 전략입니다. 하지만 원본 테이블 전체를 복사해야 하므로, 실행 비용이 상당히 크고 속도도 느릴 수 있습니다.Delete+Insert 전략
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 필요)
증분 전략microbatch는 dbt-core 1.9부터 지원되는 기능으로, 대규모 시계열 데이터(time-series data) 변환을 효율적으로 처리하도록 설계되었습니다. dbt-clickhouse에서는 기존 delete_insert
증분 전략을 기반으로 하며, event_time 및
batch_size 모델 구성에 따라 증분 처리를 미리 정의된 시계열 배치로 분할합니다.
대규모 변환 처리 외에도, microbatch는 다음과 같은 기능을 제공합니다:
- 실패한 배치를 재처리할 수 있습니다.
- 병렬 배치 실행을 자동으로 감지합니다.
- 백필 시 복잡한 조건부 로직이 필요하지 않습니다.
Append 전략
이 전략은 이전 버전의 dbt-clickhouse에서inserts_only 설정을 대체합니다. 이 방식은 기존 릴레이션에
새 행을 단순히 추가만 합니다.
따라서 중복 행은 제거되지 않으며, 임시 테이블이나 중간 테이블도 사용하지 않습니다. 데이터에서 중복이 허용되거나
증분 쿼리의 WHERE 절/필터로 제외되는 경우 가장 빠른
방식입니다.
insert_overwrite 전략 (Experimental)
[IMPORTANT]
현재 insert_overwrite 전략은 분산 머티리얼라이즈에서 완전히 동작하지 않습니다.
다음 단계를 수행합니다:
- 증분 모델 릴레이션과 동일한 구조를 가진 스테이징(임시) 테이블을 생성합니다:
CREATE TABLE <staging> AS <target>. - 새 레코드만(
SELECT로 생성됨) 스테이징 테이블에 삽입합니다. - 새 파티션만(스테이징 테이블에 있는 파티션) 대상 테이블에 대체합니다.
- 전체 테이블을 복사하지 않으므로 기본 전략보다 더 빠릅니다.
INSERT작업이 성공적으로 완료될 때까지 원본 테이블을 수정하지 않으므로 다른 전략보다 더 안전합니다: 중간에 실패하더라도 원본 테이블은 수정되지 않습니다.- 데이터 엔지니어링 모범 사례인 “파티션 불변성”을 구현합니다. 이를 통해 증분 및 병렬 데이터 처리, 롤백 등이 단순해집니다.
partition_by를 설정해야 합니다. 모델 구성의 다른 모든 전략별
매개변수는 무시됩니다.
머티리얼라이즈: materialized_view
materialized_view 머티리얼라이즈는 삽입 트리거 역할을 하는 ClickHouse materialized view를 생성하며, 원본 테이블의 새 행을 자동으로 변환해 대상 테이블에 삽입합니다. 이는 dbt-clickhouse에서 사용할 수 있는 가장 강력한 머티리얼라이즈 중 하나입니다.
이 머티리얼라이즈는 내용이 방대하므로 전용 페이지에서 별도로 다룹니다. 전체 문서는 **Materialized Views 가이드**를 참조하십시오.
머티리얼라이즈: 딕셔너리 (실험적)
dbt 모델은 ClickHouse 딕셔너리로 생성할 수 있습니다.dbt run을 실행할 때마다 CREATE OR REPLACE DICTIONARY를 사용하여 현재 모델 정의로 딕셔너리를 대체합니다.
구성
ClickHouse 소스를 사용하는 예시
모델의 SQL이 딕셔너리 소스 쿼리로 사용됩니다:HTTP 소스 사용 예시
source_type='http'(또는 table 옵션)를 사용하면 모델의 SQL은 소스로 사용되지 않지만, dbt에서는 여전히 본문이 필요합니다. select 1을 자리 표시자로 사용하십시오:
머티리얼라이즈: distributed_table (실험적)
분산 테이블은 다음 단계에 따라 생성됩니다:- 올바른 구조를 가져오기 위한 SQL 쿼리로 임시 뷰를 생성합니다
- 뷰를 기반으로 빈 로컬 테이블을 생성합니다
- 로컬 테이블을 기반으로 분산 테이블을 생성합니다.
- 데이터는 분산 테이블에 삽입되며, 중복 없이 세그먼트 전체에 분산됩니다.
- dbt-clickhouse 쿼리에는 이제 다음을 보장하기 위해
insert_distributed_sync = 1설정이 자동으로 포함됩니다 후속 증분 머티리얼라이즈 작업이 올바르게 실행되도록 합니다. 이로 인해 일부 분산 테이블 삽입이 예상보다 더 느리게 실행될 수 있습니다.
분산 테이블 모델 예시
생성된 마이그레이션
구성
이 머티리얼라이즈 유형에만 해당하는 구성은 아래와 같습니다:머티리얼라이즈: distributed_incremental (실험적)
분산 테이블과 같은 아이디어를 기반으로 한 증분 모델이며, 가장 큰 어려움은 모든 증분 전략을 올바르게 처리하는 것입니다.- _Append 전략_은 데이터를 분산 테이블에 그대로 삽입합니다.
- Delete+Insert 전략은 모든 세그먼트의 모든 데이터를 처리할 수 있도록 분산 임시 테이블을 생성합니다.
- _Default (Legacy) 전략_은 같은 이유로 분산 임시 테이블과 중간 테이블을 생성합니다.
분산 증분 모델 예시
생성된 마이그레이션
Snapshot
dbt snapshots는 가변 model의 행이 시간에 따라 어떻게 변하는지를 type-2 slowly changing dimensions 형태로 기록하므로, 분석가는 “과거로 거슬러 올라가” model의 이전 상태를 확인할 수 있습니다. ClickHouse 어댑터는timestamp 전략과 check 전략을 모두 지원합니다. snapshot 테이블의 새 버전을 스테이징 테이블에 빌드한 뒤 EXCHANGE TABLES로 교체하므로(server가 테이블을 exchange할 수 없는 경우에는 drop 후 rename), reader는 항상 완전한 버전의 snapshot을 보게 됩니다.
dbt 1.9부터 snapshots는 snapshots/<name>.yml 파일에 YAML로 정의합니다:
snapshots/<name>.sql에 있는 기존 Jinja 형식도 계속 동작합니다:
계약 및 제약 조건
정확히 일치하는 컬럼 유형 계약만 지원됩니다. 예를 들어,UInt32 컬럼 유형 계약은 모델이
UInt64 또는 다른 정수 유형을 반환하는 경우 실패합니다.
ClickHouse는 테이블/모델 전체에 대한 CHECK 제약 조건 만 지원합니다. 프라이머리 키, 외래 키, 고유 제약 조건 및
컬럼 수준의 CHECK 제약 조건은 지원되지 않습니다.
(프라이머리 키/ORDER BY 키는 ClickHouse 문서를 참조하십시오.)