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

일반 머티리얼라이즈 구성

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

지원되는 테이블 엔진

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

실험적으로 지원되는 테이블 엔진

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

모델 설정에 대한 참고 사항

ClickHouse에는 여러 유형/수준의 “설정”이 있습니다. 위의 모델 구성에서는 이 중 두 가지를 구성할 수 있습니다. settingsCREATE TABLE/VIEW 유형의 DDL SQL 문에서 사용되는 SETTINGS 절을 의미하며, 일반적으로 특정 ClickHouse 테이블 엔진에 특화된 설정입니다. 새로운 query_settings는 모델 머티리얼라이즈에 사용되는 INSERTDELETE 쿼리(증분 머티리얼라이즈 포함)에 SETTINGS 절을 추가하는 데 사용됩니다. ClickHouse에는 수백 개의 설정이 있으며, 어떤 것이 “table” 설정이고 어떤 것이 “user” 설정인지 항상 명확하지는 않습니다(다만 후자는 일반적으로 system.settings 테이블에서 확인할 수 있습니다). 일반적으로는 기본값 사용을 권장하며, 이러한 속성을 사용할 때는 충분히 검토하고 테스트해야 합니다.

컬럼 구성

참고: 아래 컬럼 구성 옵션을 사용하려면 모델 계약이 적용되어 있어야 합니다.

스키마 구성 예시

복합 타입 추가

dbt는 모델을 생성하는 데 사용된 SQL을 분석해 각 컬럼의 데이터 타입을 자동으로 결정합니다. 하지만 경우에 따라 이 과정에서 데이터 타입을 정확히 판별하지 못해 contract의 data_type 속성에 지정된 타입과 충돌이 발생할 수 있습니다. 이를 방지하려면 모델 SQL에서 CAST() 함수를 사용해 원하는 타입을 명시적으로 정의하는 것이 좋습니다. 예시는 다음과 같습니다:

머티리얼라이즈: 뷰

dbt 모델은 ClickHouse 뷰로 생성할 수 있으며 다음 구문으로 구성할 수 있습니다: 프로젝트 파일 (dbt_project.yml):
또는 설정 블록(models/<model_name>.sql):

머티리얼라이즈: 테이블

dbt 모델은 ClickHouse 테이블로 생성할 수 있으며 다음 구문으로 구성할 수 있습니다: 프로젝트 파일 (dbt_project.yml):
또는 config 블록(models/<model_name>.sql):

데이터 스키핑 인덱스

indexes 구성을 사용해 table 머티리얼라이즈에 데이터 스키핑 인덱스를 추가할 수 있습니다.

프로젝션

projections 구성을 사용하면 tabledistributed_table 머티리얼라이제이션에 프로젝션을 추가할 수 있습니다.
참고: 분산 테이블에서는 프로젝션이 분산 프록시 테이블이 아니라 _local 테이블에 적용됩니다.

머티리얼라이즈: incremental

테이블 모델은 dbt를 실행할 때마다 다시 생성됩니다. 이는 결과 집합(result set)이 크거나 변환이 복잡한 경우 현실적으로 어렵고 비용도 매우 많이 들 수 있습니다. 이 문제를 해결하고 빌드 시간을 줄이기 위해 dbt 모델을 증분 ClickHouse 테이블로 생성할 수 있으며, 다음 구문으로 구성합니다: dbt_project.yml의 모델 정의:
또는 models/<model_name>.sql의 구성 블록:

구성

이 머티리얼라이즈 유형에만 해당하는 구성은 아래와 같습니다:

증분 모델 전략

dbt-clickhouse는 3가지 증분 모델 전략을 지원합니다.

기본(레거시) 전략

과거 ClickHouse는 비동기식 “뮤테이션” 형태로만 업데이트와 삭제를 제한적으로 지원했습니다. 예상되는 dbt 동작을 구현하기 위해, dbt-clickhouse는 기본적으로 영향을 받지 않은(삭제되지 않았고 변경되지 않은) 모든 “기존” 레코드와 새로 추가되거나 업데이트된 레코드를 포함하는 새 임시 테이블을 생성한 다음, 이 임시 테이블을 기존 증분 모델 릴레이션과 스왑하거나 EXCHANGE합니다. 이 전략은 작업이 완료되기 전에 문제가 발생하더라도 원래 릴레이션을 보존할 수 있는 유일한 전략입니다. 하지만 원본 테이블 전체를 복사해야 하므로, 실행 비용이 상당히 크고 속도도 느릴 수 있습니다.

Delete+Insert 전략

ClickHouse는 버전 22.8에서 “경량한 삭제(lightweight deletes)“를 실험적 기능으로 추가했습니다. 경량한 삭제는 ClickHouse 데이터 파트를 다시 쓰지 않아도 되므로 ALTER TABLE … DELETE 작업보다 훨씬 빠릅니다. 증분 전략 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_timebatch_size 모델 구성에 따라 증분 처리를 미리 정의된 시계열 배치로 분할합니다. 대규모 변환 처리 외에도, microbatch는 다음과 같은 기능을 제공합니다: microbatch 사용법에 대한 자세한 내용은 공식 문서를 참조하십시오.
사용 가능한 Microbatch 구성

Append 전략

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

insert_overwrite 전략 (Experimental)

[IMPORTANT] 현재 insert_overwrite 전략은 분산 머티리얼라이즈에서 완전히 동작하지 않습니다.
다음 단계를 수행합니다:
  1. 증분 모델 릴레이션과 동일한 구조를 가진 스테이징(임시) 테이블을 생성합니다: CREATE TABLE <staging> AS <target>.
  2. 새 레코드만(SELECT로 생성됨) 스테이징 테이블에 삽입합니다.
  3. 새 파티션만(스테이징 테이블에 있는 파티션) 대상 테이블에 대체합니다.
이 접근 방식에는 다음과 같은 장점이 있습니다:
  • 전체 테이블을 복사하지 않으므로 기본 전략보다 더 빠릅니다.
  • INSERT 작업이 성공적으로 완료될 때까지 원본 테이블을 수정하지 않으므로 다른 전략보다 더 안전합니다: 중간에 실패하더라도 원본 테이블은 수정되지 않습니다.
  • 데이터 엔지니어링 모범 사례인 “파티션 불변성”을 구현합니다. 이를 통해 증분 및 병렬 데이터 처리, 롤백 등이 단순해집니다.
이 전략을 사용하려면 모델 구성에서 partition_by를 설정해야 합니다. 모델 구성의 다른 모든 전략별 매개변수는 무시됩니다.

머티리얼라이즈: materialized_view

materialized_view 머티리얼라이즈는 삽입 트리거 역할을 하는 ClickHouse materialized view를 생성하며, 원본 테이블의 새 행을 자동으로 변환해 대상 테이블에 삽입합니다. 이는 dbt-clickhouse에서 사용할 수 있는 가장 강력한 머티리얼라이즈 중 하나입니다. 이 머티리얼라이즈는 내용이 방대하므로 전용 페이지에서 별도로 다룹니다. 전체 문서는 **Materialized Views 가이드**를 참조하십시오.

머티리얼라이즈: 딕셔너리 (실험적)

ClickHouse 딕셔너리용 머티리얼라이즈를 구현하는 방법에 대한 예시는 https://github.com/ClickHouse/dbt-clickhouse/blob/main/tests/integration/adapter/dictionary/test&#95;dictionary.py의 테스트를 참조하십시오

머티리얼라이즈: distributed_table (실험적)

분산 테이블은 다음 단계에 따라 생성됩니다:
  1. 올바른 구조를 가져오기 위한 SQL 쿼리로 임시 뷰를 생성합니다
  2. 뷰를 기반으로 빈 로컬 테이블을 생성합니다
  3. 로컬 테이블을 기반으로 분산 테이블을 생성합니다.
  4. 데이터는 분산 테이블에 삽입되며, 중복 없이 세그먼트 전체에 분산됩니다.
참고:
  • dbt-clickhouse 쿼리에는 이제 다음을 보장하기 위해 insert_distributed_sync = 1 설정이 자동으로 포함됩니다 후속 증분 머티리얼라이즈 작업이 올바르게 실행되도록 합니다. 이로 인해 일부 분산 테이블 삽입이 예상보다 더 느리게 실행될 수 있습니다.

분산 테이블 모델 예시

생성된 마이그레이션

구성

이 머티리얼라이즈 유형에만 해당하는 구성은 아래와 같습니다:

머티리얼라이즈: distributed_incremental (실험적)

분산 테이블과 같은 아이디어를 기반으로 한 증분 모델이며, 가장 큰 어려움은 모든 증분 전략을 올바르게 처리하는 것입니다.
  1. _Append 전략_은 데이터를 분산 테이블에 그대로 삽입합니다.
  2. Delete+Insert 전략은 모든 세그먼트의 모든 데이터를 처리할 수 있도록 분산 임시 테이블을 생성합니다.
  3. _Default (Legacy) 전략_은 같은 이유로 분산 임시 테이블과 중간 테이블을 생성합니다.
분산 테이블은 데이터를 저장하지 않으므로 교체되는 것은 세그먼트 테이블뿐입니다. 분산 테이블은 full_refresh 모드가 활성화된 경우 또는 테이블 구조가 변경되었을 수 있는 경우에만 다시 로드됩니다.

분산 증분 모델 예시

생성된 마이그레이션

스냅샷

dbt 스냅샷은 시간의 흐름에 따라 변경되는 가변 모델의 변경 이력을 기록할 수 있도록 합니다. 이를 통해 모델에 대해 특정 시점 기준의 쿼리를 수행할 수 있으며, 분석가는 모델의 이전 상태를 “과거 시점으로 돌아가” 확인할 수 있습니다. 이 기능은 ClickHouse Connector에서 지원되며, 다음 구문을 사용해 구성합니다: snapshots/<model_name>.sql의 설정 블록:
구성에 대한 자세한 내용은 snapshot 구성 참고 페이지를 참조하세요.

계약 및 제약 조건

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