> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> dbt OSS, dbt v2 및 dbt 플랫폼에서의 ClickHouse 어댑터 지원 현황

# dbt OSS, v2 및 플랫폼(베타)

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>베타</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>베타 기능</span>
        </a>;
};

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 />

<BetaBadge link="https://github.com/ClickHouse/dbt-clickhouse/issues/660" />

dbt는 새로운 엔진 위에서 재구축되고 있으며, ClickHouse는 그 출발점부터 함께하고 있습니다. 이제 ClickHouse는 dbt OSS와 dbt v2 모두에서 새로운 Rust 기반 dbt 엔진과 함께 동작하며, 처음으로 dbt 플랫폼에서 ClickHouse에 연결할 수 있습니다. 기존 프로젝트를 변경할 필요는 없습니다. 현재 dbt Core 1.x에서 실행되는 모델, 테스트, 프로필이 새 엔진에서도 그대로 실행되며, 달라지는 것은 바이너리뿐입니다.

ClickHouse는 dbt OSS, dbt v2 및 dbt 플랫폼을 지원하는 최초의 커뮤니티 어댑터입니다. dbt의 퍼스트파티 어댑터가 ClickHouse와 함께 출시되고 있으며, dbt Labs 외부에서는 ClickHouse가 처음입니다. dbt Core 1.x Python 어댑터인 `dbt-clickhouse`는 중단되지 않습니다. dbt 1.x 릴리스에 맞춰 최신 상태로 유지하며, 두 어댑터를 병행하여 관리합니다.

<Warning>
  **프로덕션 환경에 적합하지 않습니다.** dbt OSS 및 dbt v2용 ClickHouse 어댑터와 dbt 플랫폼 연결은 아직 일반 제공(GA) 상태가 아닙니다. 개발 또는 스테이징 프로젝트에서만 사용하십시오.
</Warning>

<Note>
  **dbt Core 1.x 문서는 dbt OSS 및 dbt v2에도 적용됩니다.** 어댑터는 두 엔진에서 동일하게 동작합니다. 다른 dbt 페이지에 설명된 프로필, 모델 구성, 머티리얼라이즈, 매크로는 dbt OSS, dbt v2 및 dbt 플랫폼에서 변경 없이 동작합니다. 예외 사항은 아래의 [v1 대 v2 동등성](#parity) 표에 정리되어 있습니다.
</Note>

<Note>
  **dbt OSS**는 v2 엔진의 오픈소스(Apache 2.0) 빌드입니다. dbt v2 및 dbt 플랫폼과의 관계는 [용어 및 제공 범위](#terminology)를 참조하십시오.
</Note>

최신 진행 상황은 [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660)(v1 대비 v2 동등성, 영역별 하위 이슈 1개)과 [ClickHouse/dbt-clickhouse#555](https://github.com/ClickHouse/dbt-clickhouse/issues/555)(dbt v2)에서 확인할 수 있습니다.

<h4 id="request-access">
  dbt 플랫폼에서 ClickHouse 사용해 보기
</h4>

프라이빗 베타 테스트에 관심이 있다면 [dbt Labs 프라이빗 베타 양식](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform)을 통해 신청하십시오. 이 양식은 dbt Labs가 운영하므로, 제출한 정보는 ClickHouse가 아닌 dbt Labs로 전달됩니다. 기능이 활성화되면 dbt 문서의 [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse)를 참고하여 연결을 설정하십시오.

<h2 id="terminology">
  용어 및 제공 현황
</h2>

dbt는 여러 형태로 제공되며, 동일한 어댑터가 둘 이상의 형태에서 실행될 수 있습니다. 아래 표는 각 명칭과 현재 ClickHouse 지원 수준을 설명합니다.

| 용어 | 설명 | ClickHouse 지원 상태 및 사용 방법 |
| - | - | - |
| **dbt Core 1.x** | Python 기반 dbt 엔진으로, 오픈 소스(Apache 2.0)입니다. ClickHouse 어댑터는 `dbt-clickhouse`이며, [ClickHouse GitHub organization](https://github.com/ClickHouse/dbt-clickhouse)에서 유지 관리되고 `dbt-core`와 함께 설치됩니다. | **일반 제공, 유지 관리 중.** dbt v2와 병행하여 계속 릴리스됩니다. |
| **dbt OSS** | dbt 엔진을 Rust로 전면 재작성한 버전으로, 오픈 소스(Apache 2.0)입니다. 이 새 버전에는 v1의 모든 기능과 여러 성능 개선 사항이 포함되어 있습니다. | **베타.** dbt 문서의 [dbt v2 업그레이드 가이드](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v2)와 [v2용 ClickHouse 설정 페이지](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup?version=2)를 참고하십시오. ClickHouse 어댑터는 dbt 바이너리에 포함되어 제공되므로 별도로 설치할 패키지가 없습니다. |
| **dbt v2** | dbt OSS에 dbt Labs의 추가 기능이 더해진 형태입니다. SQL 이해, 정적 분석, LSP, VS Code 확장 기능, 컬럼 인식 등을 제공합니다. 클로즈드 소스이며 [dbt Product Licensing Agreement](https://www.getdbt.com/dbt-fusion-engine-license-agreement)에 따라 라이선스가 부여됩니다. | **베타.** 어댑터는 v2 바이너리에서 실행되지만, 새로운 SQL 기능은 아직 ClickHouse에서 사용할 수 없습니다. |
| **dbt platform** | 호스팅형 dbt로, 이전 명칭은 dbt Cloud입니다. Studio IDE, 예약 작업, 환경, Catalog, Semantic Layer를 제공합니다. 이 플랫폼은 dbt v2만 실행하므로, 플랫폼에서 ClickHouse를 사용한다는 것은 v2 어댑터를 사용한다는 의미입니다. | **프라이빗 베타.** [액세스 요청 방법](#request-access)을 참고하십시오. 설정 방법은 dbt 문서의 [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse)를 참고하십시오. |

<h2 id="beta-status">
  베타 상태
</h2>

dbt v2 어댑터는 `dbt-clickhouse`의 dbt Core 1.x 통합 테스트 스위트를 기준으로 검증하고 있습니다. 베타는 핵심 dbt 워크플로와 ClickHouse Cloud 기능 집합이 문서화된 제약 범위 내에서 동작함을 의미하며, 완전한 v1 동등성과 자가 관리형 클러스터 지원은 이후에 제공됩니다.

**현재** 어댑터는 전체 v1 테스트 스위트의 81% 이상, ClickHouse Cloud에 해당하는 테스트의 92%를 통과합니다. 모든 머티리얼라이즈 방식(`view`, `table`, `incremental`, `materialized_view`, `dictionary`, `snapshot`, `seed`, `ephemeral`)이 v1과 동등한 수준이며, 전체 테이블 구성 집합, 모델 계약, 데이터 테스트 및 단위 테스트, 문서 영속화, `clickhouse_s3source()`, dbt Core 1.x 연결 설정도 모두 지원됩니다. 남은 실패 항목은 아래에 나열된 자가 관리형 클러스터 작업과 일부 엔진 측 차이에서 비롯된 것입니다. 기능별 상세 내용은 [v1 대 v2 동등성](#parity)을 참조하십시오.

**다음 단계**: 자가 관리형 클러스터를 위한 `ON CLUSTER` DDL 및 분산 머티리얼라이즈, 권한 부여, `dbt clone`, 테이블 메타데이터 기반 `dbt source freshness`, 남은 버그 수정, 그리고 완전한 동등성을 보장하기 위한 전체 v1 테스트 스위트 통과입니다. 이 모든 작업의 진행 상황은 [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660)에서 영역별 하위 이슈로 추적되고 있습니다.

일반 제공은 로드맵에 포함되어 있으며 곧 제공될 예정입니다. 준비가 완료되면 문서를 업데이트하겠습니다.

<h3 id="out-of-scope">
  베타 범위에서 제외되는 항목
</h3>

아래에 나열된 v1 기능 격차 외에도, v2에만 있는 일부 기능은 현재 범위에 포함되지 않지만 곧 제공될 예정입니다:

* **Semantic Layer / MetricFlow.** ClickHouse 지원은 아직 추가되지 않았습니다. [dbt-labs/metricflow#2124](https://github.com/dbt-labs/metricflow/pull/2124)에서 추적 중입니다.
* **dbt v2의 ClickHouse SQL 인텔리전스**(방언 인식 유효성 검사, 정적 분석, LSP, VS Code 확장 기능의 컬럼 인식). 어댑터는 현재 dbt v2 바이너리로 실행되지만 아직 이러한 기능은 포함하지 않습니다. 그전까지 ClickHouse 프로젝트에서는 정적 분석이 `off`로 강제되며, 엔진은 컬럼 수준 계보를 기록하지 않습니다. [#736](https://github.com/ClickHouse/dbt-clickhouse/issues/736)에서 추적 중입니다.
* dbt 플랫폼에서 username 및 password 외의 **추가 인증 방식**.

<h2 id="parity">
  v1 대 v2 기능 동등성
</h2>

아래 표는 `dbt-clickhouse`(v1)에서 제공되는 기능과 dbt v2 어댑터에서의 지원 상태를 비교한 것입니다. 참고 사항에 별도로 명시하지 않은 한, 나열된 모든 기능은 v1에서 지원됩니다. 상태 컬럼은 dbt v2를 기준으로 하며, dbt OSS에도 동일하게 적용됩니다. 미구현 항목의 진행 상황은 모두 [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660)에서 추적됩니다.

<Badge color="green">지원됨</Badge> 현재 동작함 · <Badge color="yellow">부분 지원</Badge> 제한적으로 동작함 · <Badge color="red">Not yet</Badge> 구현 대기 중.

### 머티리얼라이즈

| 기능 | 동작 내용 | dbt v2 | 참고 |
| - | - | - | - |
| `view` | 표준 dbt 뷰입니다. | <Badge color="green">지원됨</Badge> | |
| `table` | 엔진 및 DDL 옵션을 적용해 전체를 재구성합니다. | <Badge color="green">지원됨</Badge> | |
| `incremental` | 새로운 행을 추가하거나 머지합니다. | <Badge color="green">지원됨</Badge> | |
| `materialized_view` | 삽입 시점에 데이터를 변환하는 ClickHouse MV입니다. | <Badge color="green">지원됨</Badge> | |
| `dictionary` | 키 lookup 및 조인에 사용하는 ClickHouse 딕셔너리입니다. | <Badge color="green">지원됨</Badge> | |
| `snapshot` | Type 2 방식의 느리게 변하는 차원입니다. | <Badge color="green">지원됨</Badge> | |
| `seed` | CSV를 테이블로 로드합니다. | <Badge color="green">지원됨</Badge> | 숫자 컬럼 타입이 `Int32`/`Float32`가 아닌 `Int64`/`Float64`로 추론됩니다. 명시적으로 지정하려면 `column_types`를 사용하십시오. |
| `ephemeral` | 인라인 CTE로, 객체가 생성되지 않습니다. | <Badge color="green">지원됨</Badge> | |
| `distributed_table`, `distributed_incremental` | 분산 엔진 뒤에 두는 세그먼트 테이블입니다. | <Badge color="red">Not yet</Badge> | |

### 모델 구성

| 기능 | 설명 | dbt v2 | 참고 |
| - | - | - | - |
| 엔진, `ORDER BY`, `PARTITION BY`, `PRIMARY KEY` | 핵심 MergeTree DDL 제어. | <Badge color="green">지원됨</Badge> | |
| TTL | 행 및 컬럼 만료. | <Badge color="green">지원됨</Badge> | |
| 테이블 및 쿼리 설정 | DDL과 삽입 시 적용되는 모델별 `SETTINGS`. | <Badge color="green">지원됨</Badge> | |
| 프로젝션, 인덱스, `sql_header` | 보조 구조 및 선행 SQL. | <Badge color="green">지원됨</Badge> | |
| 모델 계약 및 제약 조건 | 빌드 시점에 적용되는 컬럼 타입 및 제약 조건. | <Badge color="green">지원됨</Badge> | |
| 증분 모델의 스키마 진화 | `on_schema_change`가 컬럼을 추가하거나 동기화합니다. | <Badge color="green">지원됨</Badge> | |
| 컬럼 `codec` 및 `ttl` | 컬럼별 압축 및 만료. | <Badge color="green">지원됨</Badge> | |

### 테스트 및 문서

| 기능 | 설명 | dbt v2 | 참고 |
| - | - | - | - |
| 데이터 테스트 | 일반(generic) 테스트 및 단일(singular) 테스트. | <Badge color="green">지원됨</Badge> | |
| 단위 테스트 | 픽스처 입력을 기준으로 모델 로직 검증. | <Badge color="green">지원됨</Badge> | |
| 문서 영속화 | 설명이 ClickHouse comment로 기록됩니다. | <Badge color="yellow">부분 지원</Badge> | `;`이 포함된 설명은 실패합니다. |
| 카탈로그 및 문서 생성 | 문서 사이트용 컬럼 메타데이터. | <Badge color="green">지원됨</Badge> | |
| 컬럼 수준 계보 | DAG 전반에 걸친 컬럼 추적. | <Badge color="yellow">부분 지원</Badge> | SQL 컴파일러를 통해 v2에 새로 추가된 기능으로, v1에서는 사용할 수 없습니다. dbt 플랫폼 계보는 `dbt_project.yml`에서 식별자 quoting을 비활성화해야만 렌더링되며, 엔진 측 계보에는 ClickHouse SQL 방언이 필요합니다. |

### 클러스터 및 Cloud

| 기능 | 설명 | dbt v2 | 참고 |
| - | - | - | - |
| ClickHouse Cloud | 권장 베타 구성입니다. | <Badge color="green">지원됨</Badge> | |
| 다중 레플리카 일관성 | `select_sequential_consistency` 및 관련 read-after-write 설정. | <Badge color="green">지원됨</Badge> | |
| `ON CLUSTER` 및 replicated 엔진 | 자가 관리형 클러스터에서의 DDL fan-out. | <Badge color="red">Not yet</Badge> | ClickHouse Cloud의 다중 노드 클러스터는 지원됩니다. DDL 전파에 `ON CLUSTER`가 필요한 그 외 구성은 아직 지원되지 않습니다. 자가 관리형 배포에서는 단일 노드 클러스터에 대해서만 테스트하십시오. |
| `EXCHANGE TABLES` | 재구성 시 원자적 스왑. | <Badge color="green">지원됨</Badge> | |
| 사용자 정의 연결 설정 | 프로필 수준의 `custom_settings`. | <Badge color="green">지원됨</Badge> | |
| ClickHouse 서버 버전 | 최소 서버 버전. | <Badge color="green">지원됨</Badge> | 두 엔진 모두 25.3 이상. v2에서 `UUID` 컬럼을 읽으려면 26.7 이상이 필요합니다(이전 버전 서버는 `UUID`를 Arrow로 변환할 수 없습니다). |

### 매크로 및 작업

| 기능 | 동작 내용 | dbt v2 | 참고 |
| - | - | - | - |
| S3 테이블 함수 매크로 | `clickhouse_s3source()`가 모델에서 S3를 직접 읽습니다. | <Badge color="green">지원됨</Badge> | |
| 크로스 데이터베이스 매크로 | `dbt-utils`에 포함된 것과 같은 헬퍼입니다. | <Badge color="green">지원됨</Badge> | |
| 권한 부여 | 모델 구성에서 생성되는 `GRANT` SQL 문입니다. | <Badge color="red">Not yet</Badge> | |
| `dbt clone` | 환경 간 zero-copy `CLONE AS`입니다. | <Badge color="red">Not yet</Badge> | |
| 실행 결과의 Query ID | `system.query_log`와 연계하기 위한 `adapter_response` 내 `query_id`입니다. | <Badge color="red">Not yet</Badge> | |
| `query-comment` | 쿼리 주석 구성입니다. | <Badge color="red">Not yet</Badge> | `query-comment: null`은 아직 적용되지 않습니다. |
| 카탈로그 통합(Iceberg) | 외부 카탈로그로 구체화합니다. | <Badge color="red">Not yet</Badge> | v1에서도 지원되지 않으며, 우회 방법이 문서화되어 있습니다. |

### 연결 및 인증

| 기능 | 설명 | dbt v2 | 참고 |
| - | - | - | - |
| Protocol | dbt가 ClickHouse와 통신하는 방식입니다. | <Badge color="green">지원됨</Badge> | v2에서는 ADBC(HTTP 기반 Arrow), v1에서는 HTTP 및 네이티브 프로토콜을 사용합니다. |
| Username and password, TLS | 표준 인증입니다. | <Badge color="green">지원됨</Badge> | |
| mTLS 클라이언트 인증서 | `client_cert`, `client_cert_key`, `verify`. | <Badge color="red">Not yet</Badge> | 드라이버 작업이 필요합니다. 해당 키는 허용되지만 무시됩니다. |
| HTTP 클라이언트 옵션 | `connect_timeout`, `send_receive_timeout`, `sync_request_timeout`, `compress_block_size`, `server_host_name`. | <Badge color="red">Not yet</Badge> | 허용되지만 무시되며, `server_host_name`은 사용할 수 없습니다. |