일반 머티리얼라이즈 구성
지원되는 테이블 엔진
참고: materialized view의 경우, 모든 *MergeTree 엔진이 지원됩니다.
실험적으로 지원되는 테이블 엔진
위 엔진 중 하나로 dbt에서 ClickHouse에 연결하는 데 문제가 발생하면 여기에
이슈를 보고해 주십시오.
모델 설정에 대한 참고 사항
settings는 CREATE TABLE/VIEW
유형의 DDL SQL 문에서 사용되는 SETTINGS
절을 의미하며, 일반적으로 특정 ClickHouse 테이블 엔진에 특화된 설정입니다. 새로운
query_settings는 모델 머티리얼라이즈에 사용되는 INSERT 및 DELETE 쿼리(증분 머티리얼라이즈
포함)에 SETTINGS 절을 추가하는 데 사용됩니다.
ClickHouse에는 수백 개의 설정이 있으며, 어떤 것이 “table” 설정이고 어떤 것이 “user”
설정인지 항상 명확하지는 않습니다(다만 후자는 일반적으로
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 테이블에 적용됩니다.
머티리얼라이즈: incremental
dbt_project.yml의 모델 정의:
models/<model_name>.sql의 구성 블록:
구성
증분 모델 전략
dbt-clickhouse는 3가지 증분 모델 전략을 지원합니다.
기본(레거시) 전략
Delete+Insert 전략
delete+insert는
경량한 삭제를 활용하여
“legacy” 전략보다 훨씬 뛰어난 성능의 증분 머티리얼라이즈를 구현합니다. 하지만 이 전략을 사용할 때는 다음과 같은 중요한
주의 사항이 있습니다:
allow_experimental_lightweight_delete=1설정을 사용해 ClickHouse 서버에서 경량한 삭제를 활성화해야 하며, 또는 프로필에서use_lw_deletes=true를 설정해야 합니다 (이 경우 dbt 세션에 해당 설정이 활성화됩니다)- 경량한 삭제는 이제 프로덕션 환경에서 사용할 수 있지만, 23.3 이전 버전의 ClickHouse에서는 성능 및 기타 문제가 있을 수 있습니다.
- 이 전략은 영향을 받는 테이블/릴레이션에서 직접 동작하며(중간 또는 임시 테이블을 생성하지 않음), 작업 중 문제가 발생하면 증분 모델의 데이터가 유효하지 않은 상태가 될 가능성이 높습니다
- 경량한 삭제를 사용할 때 dbt-clickhouse는
allow_nondeterministic_mutations설정을 활성화합니다. 매우 드문 경우지만 비결정적 incremental_predicates를 사용하면 업데이트되거나 삭제된 항목에 대해 경쟁 상태가 발생할 수 있으며(관련 로그 메시지가 ClickHouse 로그에 기록될 수 있음), 일관된 결과를 보장하려면 증분 프레디케이트에는 증분 머티리얼라이즈 중에 수정되지 않을 데이터에 대한 하위 쿼리만 포함해야 합니다.
Microbatch 전략 (dbt-core >= 1.9 필요)
microbatch는 dbt-core 1.9부터 지원되는 기능으로, 대규모 시계열 데이터(time-series data) 변환을 효율적으로 처리하도록 설계되었습니다. dbt-clickhouse에서는 기존 delete_insert
증분 전략을 기반으로 하며, event_time 및
batch_size 모델 구성에 따라 증분 처리를 미리 정의된 시계열 배치로 분할합니다.
대규모 변환 처리 외에도, microbatch는 다음과 같은 기능을 제공합니다:
- 실패한 배치를 재처리할 수 있습니다.
- 병렬 배치 실행을 자동으로 감지합니다.
- 백필 시 복잡한 조건부 로직이 필요하지 않습니다.
사용 가능한 Microbatch 구성
Append 전략
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 가이드**를 참조하십시오.
머티리얼라이즈: 딕셔너리 (실험적)
머티리얼라이즈: distributed_table (실험적)
- 올바른 구조를 가져오기 위한 SQL 쿼리로 임시 뷰를 생성합니다
- 뷰를 기반으로 빈 로컬 테이블을 생성합니다
- 로컬 테이블을 기반으로 분산 테이블을 생성합니다.
- 데이터는 분산 테이블에 삽입되며, 중복 없이 세그먼트 전체에 분산됩니다.
- dbt-clickhouse 쿼리에는 이제 다음을 보장하기 위해
insert_distributed_sync = 1설정이 자동으로 포함됩니다 후속 증분 머티리얼라이즈 작업이 올바르게 실행되도록 합니다. 이로 인해 일부 분산 테이블 삽입이 예상보다 더 느리게 실행될 수 있습니다.
분산 테이블 모델 예시
생성된 마이그레이션
구성
머티리얼라이즈: distributed_incremental (실험적)
- _Append 전략_은 데이터를 분산 테이블에 그대로 삽입합니다.
- Delete+Insert 전략은 모든 세그먼트의 모든 데이터를 처리할 수 있도록 분산 임시 테이블을 생성합니다.
- _Default (Legacy) 전략_은 같은 이유로 분산 임시 테이블과 중간 테이블을 생성합니다.
분산 증분 모델 예시
생성된 마이그레이션
스냅샷
snapshots/<model_name>.sql의 설정 블록:
계약 및 제약 조건
UInt32 컬럼 유형 계약은 모델이
UInt64 또는 다른 정수 유형을 반환하는 경우 실패합니다.
ClickHouse는 테이블/모델 전체에 대한 CHECK 제약 조건 만 지원합니다. 프라이머리 키, 외래 키, 고유 제약 조건 및
컬럼 수준의 CHECK 제약 조건은 지원되지 않습니다.
(프라이머리 키/ORDER BY 키는 ClickHouse 문서를 참조하십시오.)