> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> dbt를 사용해 ClickHouse에서 데이터를 변환하고 모델링할 수 있습니다

# dbt와 ClickHouse 통합

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            ClickHouse 지원
        </div>;
};

<ClickHouseSupportedBadge />

<div id="dbt-clickhouse-adapter">
  ## dbt-clickhouse 어댑터
</div>

**dbt**(data build tool)는 분석 엔지니어가 SELECT SQL 문만 작성하여 웨어하우스의 데이터를 변환할 수 있게 해줍니다. dbt는 이러한 SELECT SQL 문을 테이블과 뷰 형태의 데이터베이스 객체로 구체화하여 [Extract Load and Transform (ELT)](https://en.wikipedia.org/wiki/Extract,_load,_transform)의 T를 수행합니다. SELECT SQL 문으로 정의된 모델을 생성할 수 있습니다.

dbt에서는 이러한 모델을 서로 참조하고 여러 계층으로 쌓아 더 높은 수준의 개념을 구성할 수 있습니다. 모델을 연결하는 데 필요한 상용구 SQL은 자동으로 생성됩니다. 또한 dbt는 모델 간의 종속성을 식별하고 방향성 비순환 그래프(DAG)를 사용해 적절한 순서로 생성되도록 합니다.

dbt는 [ClickHouse에서 지원하는 어댑터](https://github.com/ClickHouse/dbt-clickhouse)를 통해 ClickHouse와 호환됩니다.

<div id="related-pages">
  ## 관련 페이지
</div>

| 페이지                                                                                                              | 설명                                   |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| [기능 및 구성](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations)                  | 사용 가능한 기능과 일반 구성에 대한 설명              |
| [머티리얼라이즈](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/materializations)                             | 지원되는 머티리얼라이즈와 해당 구성                  |
| [materialized views](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view) | materialized\_view 머티리얼라이즈에 대한 상세 문서 |
| [가이드](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/guides)                                           | ClickHouse와 함께 dbt를 사용하는 방법에 대한 가이드  |

<div id="supported-features">
  ## 지원되는 기능
</div>

지원되는 기능 목록:

* [x] 테이블 머티리얼라이즈
* [x] 뷰 머티리얼라이즈
* [x] 증분 머티리얼라이즈
* [x] Microbatch 증분 머티리얼라이즈
* [x] Materialized View 머티리얼라이즈 (`TO` 형식의 MATERIALIZED VIEW 사용, Experimental)
* [x] 시드
* [x] 소스
* [x] 문서 생성
* [x] 테스트
* [x] 스냅샷
* [x] 대부분의 dbt-utils 매크로(이제 dbt-core에 포함됨)
* [x] 임시 머티리얼라이즈
* [x] 분산 테이블 머티리얼라이즈(Experimental)
* [x] 분산 증분 머티리얼라이즈(Experimental)
* [x] Contracts
* [x] ClickHouse 전용 컬럼 구성(코덱, TTL...)
* [x] ClickHouse 전용 테이블 설정(인덱스, 프로젝션...)

dbt-core 1.10까지의 모든 기능을 지원하며, `--sample` 플래그를 포함하고 향후 릴리스에 대비한 모든 deprecation 경고도 수정되었습니다. **Catalog 통합**(예: Iceberg)은 dbt 1.10에서 도입되었지만, 아직 어댑터에서 네이티브로 지원되지는 않으며 우회 방법을 사용할 수 있습니다. 자세한 내용은 [Catalog Support section](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations#catalog-support)을 참조하십시오.

이 어댑터는 아직 [dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-overview) 내에서 사용할 수 없지만, 곧 제공될 예정입니다. 자세한 내용은 지원팀에 문의하십시오.

<div id="concepts-and-supported-materializations">
  ## dbt 개념 및 지원되는 머티리얼라이즈
</div>

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

dbt는 5가지 머티리얼라이즈 타입을 제공합니다. 이들 모두 `dbt-clickhouse`에서 지원됩니다.

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

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

ClickHouse용 [현재 어댑터](https://github.com/silentsokolov/dbt-clickhouse)는 **dictionary**, **distributed table**, **distributed incremental** 머티리얼라이즈도 지원합니다. 또한 이 어댑터는 dbt [snapshots](https://docs.getdbt.com/docs/building-a-dbt-project/snapshots#check-strategy)와 [seeds](https://docs.getdbt.com/docs/building-a-dbt-project/seeds)도 지원합니다.

다음은 `dbt-clickhouse`의 [실험적 기능](/docs/ko/reference/settings/beta-and-experimental-features)입니다.

| 유형                              | 지원 여부                             | 세부 사항                                                                                                                                                                                                                      |
| ------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Materialized View 머티리얼라이즈       | 예. explicit target을 사용한 생성은 베타입니다 | [materialized view](/docs/ko/reference/statements/create/view#materialized-view)를 생성합니다.                                                                                                                                        |
| Distributed table 머티리얼라이즈       | 예, Experimental                   | [distributed table](/docs/ko/reference/engines/table-engines/special/distributed)를 생성합니다.                                                                                                                                       |
| Distributed incremental 머티리얼라이즈 | 예, Experimental                   | distributed table과 같은 아이디어를 기반으로 하는 incremental 모델입니다. 모든 전략이 지원되는 것은 아니므로, 자세한 내용은 [해당 문서 섹션](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental)을 참조하십시오. |
| Dictionary 머티리얼라이즈              | 예, Experimental                   | [dictionary](/docs/ko/reference/engines/table-engines/special/dictionary)를 생성합니다.                                                                                                                                               |

<div id="setup-of-dbt-and-the-clickhouse-adapter">
  ## dbt와 ClickHouse 어댑터 설정
</div>

<div id="install-dbt-core-and-dbt-clickhouse">
  ### dbt-core 및 dbt-clickhouse 설치
</div>

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

```sh theme={null}
pip install dbt-core dbt-clickhouse
```

<div id="provide-dbt-with-the-connection-details-for-our-clickhouse-instance">
  ### dbt에 ClickHouse 인스턴스의 연결 정보를 제공하십시오.
</div>

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

```yaml theme={null}
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 프로토콜) 사용
```

<div id="create-a-dbt-project">
  ### dbt 프로젝트 만들기
</div>

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

```sh theme={null}
dbt init project_name
```

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

```yaml theme={null}
profile: 'clickhouse-service'
```

<div id="test-connection">
  ### 연결 테스트
</div>

CLI 도구에서 `dbt debug`를 실행하여 dbt가 ClickHouse에 연결할 수 있는지 확인합니다. 응답에 `Connection test: [OK connection ok]`가 포함되면 연결이 성공한 것입니다.

dbt를 ClickHouse와 함께 사용하는 방법을 더 자세히 알아보려면 [가이드 페이지](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/guides)로 이동하십시오.

<div id="testing-and-deploying-your-models-ci-cd">
  ### 모델 테스트 및 배포(CI/CD)
</div>

dbt 프로젝트를 테스트하고 배포하는 방법은 다양합니다. dbt는 [모범 사례 워크플로](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows)와 [CI job](https://docs.getdbt.com/docs/deploy/ci-jobs)에 대한 몇 가지 권장 사항을 제공합니다. 여기에서는 여러 전략을 살펴보겠지만, 이러한 전략은 구체적인 사용 사례에 맞게 크게 조정해야 할 수 있다는 점을 염두에 두십시오.

<div id="ci-with-simple-data-tests-and-unit-tests">
  #### 간단한 데이터 테스트와 단위 테스트를 활용한 CI/CD
</div>

CI 파이프라인을 빠르게 시작하는 간단한 방법 중 하나는 job 내에서 ClickHouse 클러스터를 실행한 다음, 이를 대상으로 모델을 실행하는 것입니다. 모델을 실행하기 전에 이 클러스터에 데모 데이터를 삽입할 수 있습니다. 또는 [seed](https://docs.getdbt.com/reference/commands/seed)를 사용해 프로덕션 데이터의 일부만 스테이징 환경에 채울 수도 있습니다.

데이터가 삽입되면 [데이터 테스트](https://docs.getdbt.com/docs/build/data-tests)와 [단위 테스트](https://docs.getdbt.com/docs/build/unit-tests)를 실행할 수 있습니다.

CD 단계는 프로덕션 ClickHouse 클러스터를 대상으로 `dbt build`를 실행하는 정도로도 충분합니다.

<div id="more-complete-ci-stage">
  #### 더 완전한 CI/CD 단계: 최신 데이터를 사용하고, 영향받는 모델만 테스트하기
</div>

일반적인 전략 중 하나는 수정된 모델(및 해당 업스트림/다운스트림 의존성)만 다시 배포하는 [Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci) job을 사용하는 것입니다. 이 접근 방식은 프로젝트 실행 시간을 줄이고 환경 간 스키마 드리프트(스키마 드리프트)가 발생하지 않도록 하기 위해 프로덕션 실행의 artifact(즉, [dbt manifest](https://docs.getdbt.com/reference/artifacts/manifest-json))를 활용합니다.

개발 환경을 서로 일치된 상태로 유지하고 오래된 배포를 기준으로 모델을 실행하는 일을 방지하려면 [clone](https://docs.getdbt.com/reference/commands/clone) 또는 [defer](https://docs.getdbt.com/reference/node-selection/defer)까지 사용할 수 있습니다.

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

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

CI 테스트에 전용 환경을 사용하면 프로덕션 환경에 영향을 주지 않고 수동 테스트도 수행할 수 있습니다. 예를 들어, 테스트를 위해 BI 도구가 이 환경을 가리키도록 설정할 수 있습니다.

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

<div id="troubleshooting-common-issues">
  ## 일반적인 문제 해결
</div>

<div id="troubleshooting-connections">
  ### 연결
</div>

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

* 엔진은 [지원되는 엔진](/docs/ko/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#supported-table-engines) 중 하나여야 합니다.
* 데이터베이스에 액세스할 수 있는 충분한 권한이 있어야 합니다.
* 데이터베이스의 기본 테이블 엔진을 사용하지 않는 경우, 모델
  구성에서 테이블 엔진을 지정해야 합니다.

<div id="understanding-long-running-operations">
  ### 장시간 실행되는 작업 이해하기
</div>

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

<div id="limitations">
  ## 제한 사항
</div>

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

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

<div id="fivetran">
  ## Fivetran
</div>

`dbt-clickhouse` connector는 [Fivetran transformations](https://fivetran.com/docs/transformations/dbt)에서도 사용할 수 있으며, `dbt`를 사용해 Fivetran 플랫폼 내에서 직접 원활하게 통합 및 변환 작업을 수행할 수 있습니다.