dbt와 ClickHouse 통합

dbt-clickhouse 어댑터

dbt(data build tool)는 분석 엔지니어가 SELECT SQL 문만 작성하여 웨어하우스의 데이터를 변환할 수 있게 해줍니다. dbt는 이러한 SELECT SQL 문을 테이블과 뷰 형태의 데이터베이스 객체로 구체화하여 Extract Load and Transform (ELT)의 T를 수행합니다. SELECT SQL 문으로 정의된 모델을 생성할 수 있습니다. dbt에서는 이러한 모델을 서로 참조하고 여러 계층으로 쌓아 더 높은 수준의 개념을 구성할 수 있습니다. 모델을 연결하는 데 필요한 상용구 SQL은 자동으로 생성됩니다. 또한 dbt는 모델 간의 종속성을 식별하고 방향성 비순환 그래프(DAG)를 사용해 적절한 순서로 생성되도록 합니다. dbt는 ClickHouse에서 지원하는 어댑터를 통해 ClickHouse와 호환됩니다.

페이지	설명
기능 및 구성	사용 가능한 기능과 일반 구성에 대한 설명
머티리얼라이즈	지원되는 머티리얼라이즈와 해당 구성
materialized views	materialized_view 머티리얼라이즈에 대한 상세 문서
가이드	ClickHouse와 함께 dbt를 사용하는 방법에 대한 가이드

지원되는 기능

지원되는 기능 목록: dbt-core 1.10까지의 모든 기능을 지원하며, --sample 플래그를 포함하고 향후 릴리스에 대비한 모든 deprecation 경고도 수정되었습니다. Catalog 통합(예: Iceberg)은 dbt 1.10에서 도입되었지만, 아직 어댑터에서 네이티브로 지원되지는 않으며 우회 방법을 사용할 수 있습니다. 자세한 내용은 Catalog Support section을 참조하십시오. 이 어댑터는 아직 dbt Cloud 내에서 사용할 수 없지만, 곧 제공될 예정입니다. 자세한 내용은 지원팀에 문의하십시오.

dbt 개념 및 지원되는 머티리얼라이즈

dbt는 모델(model)이라는 개념을 도입합니다. 모델은 여러 테이블을 조인할 수도 있는 SQL 문으로 정의됩니다. 모델은 여러 방식으로 “materialized”될 수 있습니다. 머티리얼라이즈는 모델의 SELECT 쿼리에 대한 빌드 전략을 의미합니다. 머티리얼라이즈의 내부 코드는 사용자의 SELECT 쿼리를 SQL 문으로 감싸 새로운 릴레이션을 생성하거나 기존 릴레이션을 업데이트하는 보일러플레이트 SQL입니다. dbt는 5가지 머티리얼라이즈 타입을 제공합니다. 이들 모두 dbt-clickhouse에서 지원됩니다.

view (기본값): 모델이 데이터베이스에서 뷰로 빌드됩니다. ClickHouse에서는 view로 빌드됩니다.
table: 모델이 데이터베이스에서 테이블로 빌드됩니다. ClickHouse에서는 table로 빌드됩니다.
ephemeral: 모델은 데이터베이스에 직접 빌드되지 않고, 대신 이를 참조하는 모델에 CTE(공통 테이블 표현식)로 포함됩니다.
증분: 모델은 처음에는 테이블로 materialize되며, 이후 실행에서는 dbt가 테이블에 새 행을 삽입하고 변경된 행을 업데이트합니다.
materialized view: 모델이 데이터베이스에서 materialized view로 빌드됩니다. ClickHouse에서는 materialized view로 빌드됩니다.

추가 구문과 절을 통해 기반 데이터가 변경될 때 이러한 모델을 어떻게 업데이트할지 정의합니다. dbt는 일반적으로 성능이 문제가 되기 전까지는 view 머티리얼라이즈으로 시작할 것을 권장합니다. table 머티리얼라이즈은 저장소 사용량이 증가하는 대신 모델의 쿼리 결과를 테이블로 저장하여 쿼리 시점 성능을 향상합니다. 증분 방식은 여기에서 한 단계 더 나아가, 이후 기반 데이터의 업데이트가 대상 테이블에 반영되도록 합니다. 다음은 dbt-clickhouse의 실험적 기능입니다.

유형	지원 여부	세부 사항
Materialized View 머티리얼라이즈	예. explicit target을 사용한 생성은 베타입니다	materialized view를 생성합니다.
분산 테이블 머티리얼라이즈	예, Experimental	분산 테이블를 생성합니다.
분산 증분 머티리얼라이즈	예, Experimental	분산 테이블과 같은 아이디어를 기반으로 하는 증분 모델입니다. 모든 전략이 지원되는 것은 아니므로, 자세한 내용은 해당 문서 섹션을 참조하십시오.
딕셔너리 머티리얼라이즈	예, Experimental	dictionary를 생성합니다.

dbt와 ClickHouse 어댑터 설정

dbt-core 및 dbt-clickhouse 설치

dbt는 명령줄 인터페이스(CLI) 설치를 위한 여러 옵션을 제공하며, 자세한 내용은 여기에서 확인할 수 있습니다. dbt와 dbt-clickhouse는 모두 pip로 설치하는 것이 좋습니다.

pip install dbt-core dbt-clickhouse

dbt에 ClickHouse 인스턴스의 연결 정보를 제공하십시오.

~/.dbt/profiles.yml 파일에서 clickhouse-service 프로필을 구성하고 스키마(schema), 호스트, 포트, 사용자 이름, 비밀번호 속성을 설정하십시오. 연결 구성 옵션의 전체 목록은 기능 및 구성 페이지에서 확인할 수 있습니다:

clickhouse-service:
  target: dev
  outputs:
    dev:
      type: clickhouse
      schema: [ default ] # dbt 모델용 ClickHouse 데이터베이스

      # 선택 사항
      host: [ localhost ]
      port: [ 8123 ]  # secure 및 driver 설정에 따라 기본값은 8123, 8443, 9000, 9440 
      user: [ default ] # 모든 데이터베이스 작업에 사용할 사용자
      password: [ <empty string> ] # 사용자 비밀번호
      secure: True  # TLS(네이티브 프로토콜) 또는 HTTPS(HTTP 프로토콜) 사용

dbt 프로젝트 만들기

이제 이 프로필을 기존 프로젝트 중 하나에서 사용하거나, 다음 명령으로 새 프로젝트를 만들 수 있습니다:

dbt init project_name

project_name 디렉터리에서 dbt_project.yml 파일을 수정하여 ClickHouse 서버에 연결할 프로필 이름을 지정합니다.

profile: 'clickhouse-service'

연결 테스트

CLI 도구에서 dbt debug를 실행하여 dbt가 ClickHouse에 연결할 수 있는지 확인합니다. 응답에 Connection test: [OK connection ok]가 포함되면 연결이 성공한 것입니다. dbt를 ClickHouse와 함께 사용하는 방법을 더 자세히 알아보려면 가이드 페이지로 이동하십시오.

모델 테스트 및 배포(CI/CD)

dbt 프로젝트를 테스트하고 배포하는 방법은 다양합니다. dbt는 모범 사례 워크플로와 CI job에 대한 몇 가지 권장 사항을 제공합니다. 여기에서는 여러 전략을 살펴보겠지만, 이러한 전략은 구체적인 사용 사례에 맞게 크게 조정해야 할 수 있다는 점을 염두에 두십시오.

간단한 데이터 테스트와 단위 테스트를 활용한 CI/CD

CI 파이프라인을 빠르게 시작하는 간단한 방법 중 하나는 job 내에서 ClickHouse 클러스터를 실행한 다음, 이를 대상으로 모델을 실행하는 것입니다. 모델을 실행하기 전에 이 클러스터에 데모 데이터를 삽입할 수 있습니다. 또는 seed를 사용해 프로덕션 데이터의 일부만 스테이징 환경에 채울 수도 있습니다. 데이터가 삽입되면 데이터 테스트와 단위 테스트를 실행할 수 있습니다. CD 단계는 프로덕션 ClickHouse 클러스터를 대상으로 dbt build를 실행하는 정도로도 충분합니다.

더 완전한 CI/CD 단계: 최신 데이터를 사용하고, 영향받는 모델만 테스트하기

일반적인 전략 중 하나는 수정된 모델(및 해당 업스트림/다운스트림 의존성)만 다시 배포하는 Slim CI job을 사용하는 것입니다. 이 접근 방식은 프로젝트 실행 시간을 줄이고 환경 간 스키마 드리프트(스키마 드리프트)가 발생하지 않도록 하기 위해 프로덕션 실행의 artifact(즉, dbt manifest)를 활용합니다. 개발 환경을 서로 일치된 상태로 유지하고 오래된 배포를 기준으로 모델을 실행하는 일을 방지하려면 clone 또는 defer까지 사용할 수 있습니다. ClickHouse에서 dbt clone은 zero-copy CLONE 문을 사용하여 MergeTree 테이블을 복사합니다. 자세한 내용은 아래의 dbt clone으로 모델 복제하기를 참조하십시오. 프로덕션 환경 운영에 영향을 주지 않도록 테스트 환경(즉, 스테이징 환경)에는 전용 ClickHouse 클러스터 또는 서비스를 사용하는 것을 권장합니다. 테스트 환경이 실제 운영을 잘 반영하도록 하려면 프로덕션 데이터의 일부를 사용하고, 환경 간 스키마 드리프트를 방지하는 방식으로 dbt를 실행하는 것이 중요합니다.

테스트에 최신 데이터가 필요하지 않다면 프로덕션 데이터의 Backup을 스테이징 환경으로 복원할 수 있습니다.
테스트에 최신 데이터가 필요하다면 remoteSecure() 테이블 함수와 갱신 가능 구체화 뷰를 조합해 원하는 주기로 데이터를 삽입할 수 있습니다. 또 다른 방법으로는 객체 스토리지를 중간 계층으로 사용해 프로덕션 서비스에서 데이터를 주기적으로 기록한 뒤, 객체 스토리지 테이블 함수 또는 ClickPipes(지속적인 수집용)를 사용해 스테이징 환경으로 가져오는 것입니다.

CI 테스트에 전용 환경을 사용하면 프로덕션 환경에 영향을 주지 않고 수동 테스트도 수행할 수 있습니다. 예를 들어, 테스트를 위해 BI 도구가 이 환경을 가리키도록 설정할 수 있습니다. 배포(즉, CD 단계)의 경우 변경된 모델만 업데이트할 수 있도록 프로덕션 배포의 artifact를 사용하는 것을 권장합니다. 이를 위해서는 dbt artifact용 중간 스토리지로 객체 스토리지(예: S3)를 설정해야 합니다. 설정이 완료되면 dbt build --select state:modified+ --state path/to/last/deploy/state.json와 같은 명령을 실행하여 프로덕션의 마지막 실행 이후 변경된 내용을 기준으로 필요한 최소한의 모델만 선택적으로 다시 빌드할 수 있습니다.

`dbt clone`을 사용한 모델 복제

dbt-clickhouse 1.10.1부터 dbt clone 명령어는 MergeTree 계열 엔진을 사용하는 테이블로 머티리얼라이즈된 모델을 복제할 때 ClickHouse의 zero-copy CREATE OR REPLACE TABLE ... CLONE AS ... 문을 사용합니다. 기본 데이터 파트를 중복하지 않고 테이블 사본을 생성하므로, 프로덕션 상태를 기반으로 개발 또는 Slim CI 환경을 구성하는 등 환경을 빠르고 저렴하게 동기화할 수 있습니다. 이 방식으로 복제할 수 없는 모델은 소스 릴레이션을 가리키는 뷰를 생성하는 dbt의 기본 동작으로 폴백됩니다.

MergeTree 이외의 엔진을 사용하는 테이블
분산 머티리얼라이즈

materialized view 모델은 대상 테이블만 복제되며, materialized view 자체는 복제된 테이블을 기반으로 생성됩니다.

일반적인 문제 해결

연결

dbt에서 ClickHouse에 연결하는 데 문제가 발생하면 다음 사항을 충족하는지 확인하십시오:

엔진은 지원되는 엔진 중 하나여야 합니다.
데이터베이스에 액세스할 수 있는 충분한 권한이 있어야 합니다.
데이터베이스의 기본 테이블 엔진을 사용하지 않는 경우, 모델 구성에서 테이블 엔진을 지정해야 합니다.

장시간 실행되는 작업 이해하기

일부 작업은 특정 ClickHouse 쿼리로 인해 예상보다 오래 걸릴 수 있습니다. 어떤 쿼리가 더 오래 걸리는지 자세히 파악하려면 로그 수준을 debug로 높이십시오 — 그러면 각 쿼리에 소요된 시간이 출력됩니다. 예를 들어, dbt 명령에 --log-level debug를 추가하면 됩니다.

dbt 실행과 ClickHouse 쿼리 연결

서버 측 세부 정보를 확인하려면 dbt-clickhouse 1.10.1부터 어댑터가 실행하는 각 SQL 문에 고유한 쿼리 ID(UUID4)가 할당되며, 이 ID는 ClickHouse로 전달됩니다. model의 주 SQL 문 ID는 dbt 결과의 adapter_response에 반환되므로 run_results.json과 같은 dbt artifact에서 확인할 수 있습니다. system.query_log table에서 이 ID를 조회하여 해당 SQL 문의 실행 시간과 리소스 사용량을 확인할 수 있습니다:

SELECT query_id, query, query_duration_ms, read_rows, memory_usage
FROM system.query_log
WHERE query_id = '<query_id from run_results.json>'
  AND type = 'QueryFinish'

머티리얼라이즈는 일반적으로 모델당 여러 SQL 문(DDL, 삽입 등)을 실행하며, 각 SQL 문에는 고유한 쿼리 ID가 있습니다. run_results.json의 쿼리 ID는 모델의 기본 SQL 문만 식별합니다. 실행에 포함된 모든 SQL 문을 찾으려면 각 쿼리 텍스트에 포함된 dbt 쿼리 주석을 기준으로 system.query_log를 필터링하십시오. 쿼리 ID를 사용하면 dbt artifact를 사용하는 관측성 도구(예: Elementary)에서 dbt 모델 실행을 system.query_log의 항목에 자동으로 연결할 수도 있습니다.

제한 사항

현재 dbt용 ClickHouse 어댑터에는 알아두어야 할 몇 가지 제한 사항이 있습니다:

이 플러그인은 ClickHouse 25.3 이상에서만 지원되는 구문을 사용합니다. 이전 버전의 ClickHouse는 테스트하지 않습니다. 또한 현재는 복제된 테이블(Replicated Table)도 테스트하지 않습니다.
dbt-adapter를 동시에 실행하면 충돌이 발생할 수 있습니다. 내부적으로 동일한 작업에 같은 테이블 이름을 사용할 수 있기 때문입니다. 자세한 내용은 이슈 #420을 확인하십시오.
현재 어댑터는 INSERT INTO SELECT를 사용하여 모델을 테이블로 머티리얼라이즈합니다. 즉, 실행을 다시 수행하면 데이터가 중복될 수 있습니다. 매우 큰 데이터셋(PB)의 경우 실행 시간이 매우 길어져 일부 모델은 사실상 사용하기 어려울 수 있습니다. 성능을 개선하려면 뷰를 materialized: materialization_view로 구현하여 ClickHouse Materialized Views를 사용하십시오. 또한 가능하면 GROUP BY를 활용해 각 쿼리가 반환하는 행 수를 최소화하십시오. 소스의 행 수를 그대로 유지한 채 단순 변환만 수행하는 모델보다, 데이터를 요약하는 모델을 우선하는 것이 좋습니다.
모델을 나타내기 위해 분산 테이블을 사용하려면 각 노드에 기반이 되는 복제된 테이블을 수동으로 생성해야 합니다. 그런 다음 그 위에 분산 테이블을 생성할 수 있습니다. 어댑터는 클러스터 생성을 관리하지 않습니다.
dbt가 데이터베이스에 릴레이션(테이블/뷰)을 생성할 때는 일반적으로 {{ database }}.{{ schema }}.{{ table/view id }} 형식으로 생성합니다. ClickHouse에는 스키마 개념이 없습니다. 따라서 어댑터는 {{schema}}.{{ table/view id }}를 사용하며, 여기서 schema는 ClickHouse 데이터베이스를 의미합니다.
Ephemeral 모델/CTE는 ClickHouse 삽입 SQL 문에서 INSERT INTO 앞에 배치하면 동작하지 않습니다. https://github.com/ClickHouse/ClickHouse/issues/30323을 참조하십시오. 이는 대부분의 모델에는 영향을 주지 않지만, 모델 정의와 기타 SQL 문에서 ephemeral 모델의 배치 위치에는 주의가 필요합니다.

Fivetran

dbt-clickhouse connector는 Fivetran transformations에서도 사용할 수 있으며, dbt를 사용해 Fivetran 플랫폼 내에서 직접 원활하게 통합 및 변환 작업을 수행할 수 있습니다.

Data sources

Data visualization

Data ingestion

Data integrations

SQL-clients

Tools

dbt-clickhouse 어댑터

지원되는 기능

dbt 개념 및 지원되는 머티리얼라이즈

dbt와 ClickHouse 어댑터 설정

dbt-core 및 dbt-clickhouse 설치

dbt에 ClickHouse 인스턴스의 연결 정보를 제공하십시오.

dbt 프로젝트 만들기

연결 테스트

모델 테스트 및 배포(CI/CD)

간단한 데이터 테스트와 단위 테스트를 활용한 CI/CD

더 완전한 CI/CD 단계: 최신 데이터를 사용하고, 영향받는 모델만 테스트하기

`dbt clone`을 사용한 모델 복제

일반적인 문제 해결

연결

장시간 실행되는 작업 이해하기

dbt 실행과 ClickHouse 쿼리 연결

제한 사항

Fivetran

​dbt-clickhouse 어댑터

​관련 페이지

​지원되는 기능

​dbt 개념 및 지원되는 머티리얼라이즈

​dbt와 ClickHouse 어댑터 설정

​dbt-core 및 dbt-clickhouse 설치

​dbt에 ClickHouse 인스턴스의 연결 정보를 제공하십시오.

​dbt 프로젝트 만들기

​연결 테스트

​모델 테스트 및 배포(CI/CD)

​간단한 데이터 테스트와 단위 테스트를 활용한 CI/CD

​더 완전한 CI/CD 단계: 최신 데이터를 사용하고, 영향받는 모델만 테스트하기

​dbt clone을 사용한 모델 복제

​일반적인 문제 해결

​연결

​장시간 실행되는 작업 이해하기

​dbt 실행과 ClickHouse 쿼리 연결

​제한 사항

​Fivetran

dbt-clickhouse 어댑터

관련 페이지

지원되는 기능

dbt 개념 및 지원되는 머티리얼라이즈

dbt와 ClickHouse 어댑터 설정

dbt-core 및 dbt-clickhouse 설치

dbt에 ClickHouse 인스턴스의 연결 정보를 제공하십시오.

dbt 프로젝트 만들기

연결 테스트

모델 테스트 및 배포(CI/CD)

간단한 데이터 테스트와 단위 테스트를 활용한 CI/CD

더 완전한 CI/CD 단계: 최신 데이터를 사용하고, 영향받는 모델만 테스트하기

`dbt clone`을 사용한 모델 복제

일반적인 문제 해결

연결

장시간 실행되는 작업 이해하기

dbt 실행과 ClickHouse 쿼리 연결

제한 사항

Fivetran