dbt와 ClickHouse 통합

ClickHouse Supported

dbt-clickhouse Adapter

dbt(data build tool)는 애널리틱스 엔지니어가 단순히 SELECT SQL 문을 작성하는 것만으로 데이터 웨어하우스의 데이터를 변환할 수 있도록 해줍니다. dbt는 이러한 SELECT SQL 문을 테이블과 뷰(View) 형태의 데이터베이스 객체로 구체화하여, Extract Load and Transform (ELT) 과정에서 T에 해당하는 작업을 수행합니다. SELECT 문으로 정의된 모델을 생성할 수 있습니다.

dbt 내에서 이러한 모델들은 서로를 교차 참조하고 계층화하여 더 상위 수준의 개념을 구성할 수 있습니다. 모델을 연결하는 데 필요한 반복적인 보일러플레이트 SQL 코드는 자동으로 생성됩니다. 또한 dbt는 모델 간 의존성을 식별하고, 방향 비순환 그래프(DAG, directed acyclic graph)를 사용하여 적절한 순서로 생성되도록 보장합니다.

dbt는 ClickHouse에서 지원하는 adapter를 통해 ClickHouse와 연동됩니다.

관련 페이지

페이지	설명
Features and Configurations	사용 가능한 기능과 전반적인 설정에 대한 설명
Materializations	사용 가능한 materialization과 해당 설정
Guides	ClickHouse와 함께 dbt를 사용하는 방법에 대한 가이드
Materialized Views	materialized_view materialization에 대한 구체적인 문서

지원되는 기능

지원되는 기능 목록:

• 테이블 materialization
• 뷰 materialization
• 증분(incremental) materialization
• 마이크로배치 증분(microbatch incremental) materialization
• materialized view materialization (TO 형식의 MATERIALIZED VIEW 사용, 실험적 기능)
• Seeds
• Sources
• 문서 생성(docs generate)
• 테스트
• 스냅샷
• 대부분의 dbt-utils 매크로(dbt-core에 포함됨)
• Ephemeral materialization
• 분산 테이블(distributed table) materialization (실험적 기능)
• 분산 증분(distributed incremental) materialization (실험적 기능)
• Contracts
• ClickHouse 전용 컬럼 설정(코덱(codec), TTL 등)
• ClickHouse 전용 테이블 설정(인덱스(indexes), 프로젝션(projections) 등)

--sample 플래그를 포함하여 dbt-core 1.10까지의 모든 기능을 지원하며, 향후 릴리스에 대비한 모든 폐기 예정(deprecation) 경고도 해결되어 있습니다. dbt 1.10에서 도입된 카탈로그 통합(Catalog integrations)(예: Iceberg)은 아직 어댑터에서 네이티브하게 지원되지는 않지만, 우회 방법이 있습니다. 자세한 내용은 Catalog Support 섹션을 참조하십시오.

이 어댑터는 현재 dbt Cloud 내에서는 사용할 수 없으나, 곧 제공될 예정입니다. 이에 대한 자세한 정보가 필요하면 지원팀에 문의하십시오.

dbt 개념과 지원되는 머티리얼라이제이션

dbt는 모델(model)이라는 개념을 도입합니다. 이는 잠재적으로 여러 테이블을 조인할 수 있는 SQL 문으로 정의됩니다. 모델은 여러 가지 방식으로 "머티리얼라이즈(materialize)"될 수 있습니다. 머티리얼라이제이션은 모델의 SELECT 쿼리에 대한 빌드 전략을 의미합니다. 머티리얼라이제이션을 구현하는 코드는 새로운 릴레이션을 생성하거나 기존 릴레이션을 업데이트하기 위해, 사용 중인 SELECT 쿼리를 다른 SQL 문으로 감싸는 보일러플레이트 SQL입니다.

dbt는 5가지 유형의 머티리얼라이제이션을 제공합니다. 이들은 모두 dbt-clickhouse에서 지원됩니다:

• view(기본값): 모델이 데이터베이스의 view로 빌드됩니다. ClickHouse에서는 view로 빌드됩니다.
• table: 모델이 데이터베이스의 테이블로 빌드됩니다. ClickHouse에서는 table로 빌드됩니다.
• ephemeral: 모델이 데이터베이스에 직접 빌드되지 않고, 대신 공통 테이블 표현식(CTE, Common Table Expressions)으로 종속된 모델에 포함됩니다.
• incremental: 모델이 처음에는 테이블로 머티리얼라이즈되며, 이후 실행에서는 dbt가 테이블에 새로운 행을 삽입하고 변경된 행을 업데이트합니다.
• materialized view: 모델이 데이터베이스의 materialized view로 빌드됩니다. ClickHouse에서는 materialized view로 빌드됩니다.

추가적인 구문과 절을 통해 기반 데이터가 변경될 때 이러한 모델을 어떻게 업데이트해야 하는지 정의합니다. dbt는 일반적으로 성능이 문제가 되기 전까지는 view 머티리얼라이제이션으로 시작할 것을 권장합니다. table 머티리얼라이제이션은 모델의 쿼리 결과를 테이블로 저장하여, 더 많은 스토리지를 사용하는 대신 쿼리 시간 성능을 향상시킵니다. incremental 방식은 이를 더 확장하여, 이후 기반 데이터의 업데이트가 대상 테이블에 반영되도록 합니다.

현재 ClickHouse 어댑터는 dictionary, distributed table, distributed incremental 머티리얼라이제이션도 지원합니다. 또한 이 어댑터는 dbt snapshots과 seeds를 지원합니다.

다음은 dbt-clickhouse의 실험적 기능입니다:

유형	지원 여부	세부 정보
Materialized View materialization	예. 명시적 대상 지정을 사용한 생성은 Beta 단계	materialized view를 생성합니다.
Distributed table materialization	예, 실험적	distributed table을 생성합니다.
Distributed incremental materialization	예, 실험적	distributed table과 동일한 아이디어를 기반으로 하는 incremental 모델입니다. 모든 전략이 지원되는 것은 아니므로, 자세한 내용은 해당 문서 섹션을 참조하십시오.
Dictionary materialization	예, 실험적	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, host, port, user, password 속성을 지정합니다. 연결 구성 옵션의 전체 목록은 기능 및 구성 페이지에서 확인할 수 있습니다:

clickhouse-service:
  target: dev
  outputs:
    dev:
      type: clickhouse
      schema: [ default ] # ClickHouse database for dbt models

      # Optional
      host: [ localhost ]
      port: [ 8123 ]  # Defaults to 8123, 8443, 9000, 9440 depending on the secure and driver settings 
      user: [ default ] # User for all database operations
      password: [ <empty string> ] # Password for the user
      secure: True  # Use TLS (native protocol) or HTTPS (http protocol)

dbt 프로젝트 생성

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

dbt init project_name

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

profile: 'clickhouse-service'

연결 테스트

CLI에서 dbt debug를 실행하여 dbt가 ClickHouse에 연결할 수 있는지 확인합니다. 응답에 성공적인 연결을 의미하는 Connection test: [OK connection ok]가 포함되어 있는지 확인합니다.

ClickHouse와 함께 dbt를 사용하는 방법에 대해 더 알아보려면 가이드 페이지를 참조하십시오.

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

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

간단한 데이터 테스트와 유닛 테스트를 사용하는 CI/CD

CI 파이프라인을 빠르게 시작하는 한 가지 간단한 방법은 작업(job) 안에서 ClickHouse 클러스터를 실행한 다음 해당 클러스터를 대상으로 모델을 실행하는 것입니다. 모델을 실행하기 전에 이 클러스터에 데모 데이터를 삽입할 수 있습니다. seed를 사용하여 운영 데이터의 일부로 스테이징 환경을 채울 수 있습니다.

데이터가 삽입되면 data tests와 unit tests를 실행할 수 있습니다.

CD 단계는 운영 ClickHouse 클러스터를 대상으로 dbt build를 실행하는 것만큼 단순할 수 있습니다.

더 완전한 CI/CD 단계: 최신 데이터 사용, 영향을 받은 모델만 테스트

일반적인 전략 중 하나는 수정된 모델(및 그 상위·하위 의존성)만 다시 배포하는 Slim CI 작업을 사용하는 것입니다. 이 접근 방식은 프로덕션 실행에서 생성된 아티팩트(예: dbt manifest)를 사용하여 프로젝트 실행 시간을 단축하고, 환경 간 스키마 드리프트(schema drift)가 발생하지 않도록 합니다.

개발 환경을 동기화된 상태로 유지하고 오래된 배포에 대해 모델이 실행되지 않도록 하려면 clone 또는 defer를 사용할 수 있습니다.

프로덕션 환경의 운영에 영향을 주지 않기 위해 테스트 환경(예: 스테이징 환경)에는 전용 ClickHouse 클러스터나 서비스를 사용할 것을 권장합니다. 테스트 환경이 프로덕션 환경을 잘 반영하도록 하려면, 프로덕션 데이터의 부분 집합을 사용하고, 환경 간 스키마 드리프트를 방지하는 방식으로 dbt를 실행하는 것이 중요합니다.

• 테스트에 최신 데이터가 꼭 필요하지 않은 경우, 프로덕션 데이터의 백업을 스테이징 환경으로 복원하면 됩니다.
• 테스트에 최신 데이터가 필요한 경우, remoteSecure() table function과 갱신 가능 구체화 뷰(refreshable materialized view)를 조합하여 원하는 주기로 데이터를 삽입할 수 있습니다. 또 다른 방법으로는 객체 스토리지를 중간 계층으로 사용하여 프로덕션 서비스에서 주기적으로 데이터를 기록해 두었다가, 객체 스토리지 테이블 함수나 ClickPipes(지속적인 수집용)를 사용하여 이를 스테이징 환경으로 가져오는 방법이 있습니다.

CI 테스트용 전용 환경을 사용하면 프로덕션 환경에 영향을 주지 않고 수동 테스트를 수행할 수도 있습니다. 예를 들어, BI 도구를 이 환경에 연결하여 테스트에 사용할 수 있습니다.

배포 단계(즉, CD 단계)에서는 프로덕션 배포에서 생성된 아티팩트를 사용하여 변경된 모델만 업데이트할 것을 권장합니다. 이를 위해서는 dbt 아티팩트의 중간 저장소로 객체 스토리지(예: S3)를 설정해야 합니다. 설정이 완료되면, dbt build --select state:modified+ --state path/to/last/deploy/state.json와 같은 명령을 실행하여 프로덕션에서 마지막 실행 이후 변경된 사항을 기준으로 필요한 최소 수의 모델만 선별적으로 다시 빌드할 수 있습니다.

자주 발생하는 문제 해결

Connections

dbt에서 ClickHouse로 연결하는 데 문제가 발생하는 경우, 다음 조건을 충족하는지 확인하십시오.

• 엔진은 지원되는 엔진 중 하나여야 합니다.
• 데이터베이스에 액세스할 수 있는 적절한 권한이 있어야 합니다.
• 데이터베이스의 기본 테이블 엔진이 아닌 다른 테이블 엔진을 사용하는 경우, 모델 설정에서 사용할 테이블 엔진을 명시해야 합니다.

장시간 실행 작업 이해하기

일부 작업은 특정 ClickHouse 쿼리 때문에 예상보다 오래 걸릴 수 있습니다. 어떤 쿼리가 더 오래 실행되는지 파악하려면 로그 레벨을 debug로 높이면 됩니다. 그러면 각 쿼리에 사용된 시간이 출력됩니다. 예를 들어 dbt 명령에 --log-level debug를 추가하여 설정할 수 있습니다.

제한 사항

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

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

Fivetran

dbt-clickhouse 커넥터는 Fivetran 변환에서도 사용할 수 있으며, dbt를 사용해 Fivetran 플랫폼 내에서 직접 원활한 통합과 변환을 수행할 수 있게 해줍니다.