ODBC 드라이버

ClickHouse ODBC 드라이버 문서

ClickHouse ODBC 드라이버는 ODBC와 호환되는 애플리케이션을 ClickHouse에 연결할 수 있도록 표준을 준수하는 인터페이스를 제공합니다. 이 드라이버는 ODBC API를 구현하며, 애플리케이션, BI 도구, 스크립팅 환경에서 SQL 쿼리를 실행하고 결과를 가져오며, 익숙한 방식으로 ClickHouse와 상호작용할 수 있게 해줍니다.

이 드라이버는 HTTP protocol을 사용해 ClickHouse 서버와 통신합니다. 이는 모든 ClickHouse 배포에서 지원되는 주요 프로토콜입니다. 따라서 드라이버는 로컬 설치, 클라우드 관리형 서비스, HTTP 기반 액세스만 가능한 환경을 포함한 다양한 환경에서 일관되게 동작할 수 있습니다.

드라이버의 소스 코드는 ClickHouse-ODBC GitHub Repository에서 확인할 수 있습니다.

더 나은 호환성을 위해 ClickHouse 서버를 24.11 이상 버전으로 업데이트할 것을 강력히 권장합니다.

이 드라이버는 현재 활발히 개발되고 있습니다. 일부 ODBC 기능은 아직 완전히 구현되지 않았을 수 있습니다. 현재 버전은 필수적인 연결성과 핵심 ODBC 기능을 제공하는 데 중점을 두고 있으며, 추가 기능은 향후 릴리스에서 제공될 예정입니다.

피드백은 매우 중요하며, 새로운 기능과 개선 사항의 우선순위를 정하는 데 큰 도움이 됩니다. 제약 사항, 누락된 기능, 또는 예상치 못한 동작을 발견한 경우 아래 이슈 트래커를 통해 관찰한 내용이나 기능 요청을 공유해 주십시오. https://github.com/ClickHouse/clickhouse-odbc/issues

​

Windows에 설치하기

최신 버전의 드라이버는 다음에서 확인할 수 있습니다. https://github.com/ClickHouse/clickhouse-odbc/releases/latest. 해당 페이지에서 MSI 설치 관리자를 다운로드해 실행한 다음, 간단한 설치 단계를 따르면 됩니다.

​

테스트

이 간단한 PowerShell 스크립트를 실행해 driver를 테스트할 수 있습니다. 아래 텍스트를 복사한 뒤 URL, 사용자 이름, 비밀번호를 설정하고 PowerShell 명령 프롬프트에 붙여넣으십시오 — $reader.GetValue(0)를 실행하면 ClickHouse 서버 버전이 표시되어야 합니다.

$url = "http://127.0.0.1:8123/"
$username = "default"
$password = ""
$conn = New-Object System.Data.Odbc.OdbcConnection("`
    Driver={ClickHouse ODBC Driver (Unicode)};`
    Url=$url;`
    Username=$username;`
    Password=$password")
$conn.Open()
$cmd = $conn.CreateCommand()
$cmd.CommandText = "select version()"
$reader = $cmd.ExecuteReader()
$reader.Read()
$reader.GetValue(0)
$reader.Close()
$conn.Close()

​

구성 매개변수

아래 매개변수는 ClickHouse ODBC 드라이버와의 연결을 설정할 때 가장 일반적으로 사용되는 설정입니다. 여기에는 필수 인증, 연결 동작, 데이터 처리 옵션이 포함됩니다. 지원되는 매개변수의 전체 목록은 프로젝트의 GitHub 페이지 https://github.com/ClickHouse/clickhouse-odbc에서 확인할 수 있습니다.

• Url: ClickHouse 서버의 전체 HTTP(S) 엔드포인트를 지정합니다. 여기에는 프로토콜, 호스트, 포트와 선택적 경로가 포함됩니다.
• Username: ClickHouse 서버 인증에 사용하는 사용자 이름입니다.
• Password: 지정된 사용자 이름에 연결된 비밀번호입니다. 제공되지 않으면 드라이버는 비밀번호 인증 없이 연결합니다.
• Database: 연결에 사용할 기본 데이터베이스입니다.
• Timeout: 요청을 중단하기 전에 드라이버가 서버 응답을 기다리는 최대 시간(초)입니다.
• ClientName: 클라이언트 메타데이터의 일부로 ClickHouse 서버에 전송되는 사용자 지정 식별자입니다. 추적에 사용하거나 서로 다른 애플리케이션의 트래픽을 구분하는 데 유용합니다. 이 매개변수는 드라이버가 생성하는 HTTP 요청의 User-Agent 헤더 일부로 포함됩니다.
• Compression: 요청 및 응답 payload에 대한 HTTP 압축 사용 여부를 설정합니다. 활성화하면 대역폭 사용량을 줄이고 큰 결과 집합의 성능을 개선할 수 있습니다.
• SqlCompatibilitySettings: ClickHouse가 전통적인 관계형 데이터베이스처럼 동작하도록 하는 쿼리 설정을 활성화합니다. 예를 들어 Power BI와 같은 서드파티 도구가 쿼리를 자동으로 생성할 때 유용합니다. 이러한 도구는 일반적으로 ClickHouse의 일부 고유한 동작을 인식하지 못하므로, 오류나 예상치 못한 결과를 초래하는 쿼리를 생성할 수 있습니다. 자세한 내용은 SqlCompatibilitySettings 구성 매개변수에서 사용되는 ClickHouse 설정 을 참조하십시오.

다음은 연결을 설정하기 위해 드라이버에 전달되는 전체 연결 문자열의 예시입니다.

• WSL 인스턴스에 로컬로 설치된 ClickHouse 서버

Driver={ClickHouse ODBC Driver (Unicode)};Url=http://localhost:8123/;Username=default

• ClickHouse Cloud 인스턴스.

Driver={ClickHouse ODBC Driver (Unicode)};Url=https://you-instance-url.gcp.clickhouse.cloud:8443/;Username=default;Password=your-password

​

Microsoft Power BI 통합

ODBC 드라이버를 사용하여 Microsoft Power BI를 ClickHouse 서버에 연결할 수 있습니다. Power BI는 두 가지 연결 옵션을 제공합니다. 일반 ODBC 커넥터와 ClickHouse Connector이며, 둘 다 기본 Power BI 설치에 포함되어 있습니다.

두 커넥터 모두 내부적으로 ODBC를 사용하지만, 지원 기능에는 차이가 있습니다:

• ClickHouse Connector (권장) 내부적으로 ODBC를 사용하지만 DirectQuery 모드를 지원합니다. 이 모드에서는 Power BI가 SQL 쿼리를 자동으로 생성하고 각 시각화 또는 필터 작업에 필요한 데이터만 가져옵니다.

• ODBC Connector Import 모드만 지원합니다. Power BI는 사용자가 제공한 쿼리를 실행하거나(또는 전체 테이블을 선택하여) 전체 결과 집합을 Power BI로 가져옵니다. 이후 갱신 시에는 전체 데이터셋을 다시 가져옵니다.

사용 사례에 따라 커넥터를 선택하십시오. DirectQuery는 대규모 데이터셋을 사용하는 대화형 대시보드에 가장 적합합니다. 데이터의 전체 로컬 복사본이 필요할 때는 Import 모드를 선택하십시오.

Microsoft Power BI를 ClickHouse와 통합하는 방법에 관한 자세한 내용은 Power BI 통합에 대한 ClickHouse 문서 페이지를 참조하십시오.

​

SQL 호환성 설정

ClickHouse는 고유한 SQL 방언을 사용하며, 경우에 따라 MS SQL Server, MySQL 또는 PostgreSQL 같은 다른 데이터베이스와 다르게 동작합니다. 이러한 차이는 ClickHouse 기능을 더 쉽게 사용할 수 있도록 개선된 구문을 제공하므로, 오히려 장점이 되는 경우가 많습니다.

하지만 ODBC 드라이버는 사용자가 직접 쿼리를 작성하는 환경보다 Power BI와 같은 서드파티 도구가 쿼리를 생성하는 환경에서 자주 사용됩니다. 이러한 쿼리는 일반적으로 SQL 표준의 최소한의 부분 집합에 의존합니다. 이런 경우 ClickHouse의 SQL 표준과의 차이로 인해 기대한 대로 동작하지 않거나, 예상치 못한 결과나 오류가 발생할 수 있습니다. ODBC 드라이버는 ClickHouse의 동작을 표준 SQL에 더 가깝게 맞출 수 있도록 특정 쿼리 설정을 활성화하는 추가 구성 매개변수 SqlCompatibilitySettings를 제공합니다.

​

SqlCompatibilitySettings 구성 매개변수로 활성화되는 ClickHouse 설정

이 섹션에서는 ODBC 드라이버가 어떤 설정을 변경하는지와 그 이유를 설명합니다.

cast_keep_nullable

기본적으로 ClickHouse는 널 허용 타입을 널을 허용하지 않는 타입으로 변환하는 것을 허용하지 않습니다. 하지만 많은 BI 도구는 타입 변환을 수행할 때 널 허용 타입과 널을 허용하지 않는 타입을 구분하지 않습니다. 그 결과, BI 도구가 다음과 같은 쿼리를 생성하는 경우를 흔히 볼 수 있습니다.

SELECT sum(CAST(value, 'Int32'))
FROM values

기본적으로 value 컬럼이 널 허용이면, 이 쿼리는 다음과 같은 메시지와 함께 실패합니다:

DB::Exception: Cannot convert NULL value to non-Nullable type: while executing 'FUNCTION CAST(__table1.value :: 2,
'Int32'_String :: 1) -> CAST(__table1.value, 'Int32'_String) Int32 : 0'. (CANNOT_INSERT_NULL_IN_ORDINARY_COLUMN)

cast_keep_nullable를 활성화하면 CAST의 동작이 바뀌어 인수의 널 허용 속성이 유지됩니다. 이렇게 하면 이러한 변환에서 ClickHouse의 동작이 다른 데이터베이스 및 SQL 표준에 더 가까워집니다.

prefer_column_name_to_alias

ClickHouse에서는 같은 SELECT 목록에 있는 표현식을 해당 별칭으로 참조할 수 있습니다. 예를 들어, 다음 쿼리는 반복을 줄여 더 쉽게 작성할 수 있습니다:

SELECT
    sum(value) AS S,
    count() AS C,
    S / C
FROM test

이 기능은 널리 사용되지만, 다른 데이터베이스에서는 일반적으로 동일한 SELECT 목록에서 이런 방식으로 별칭을 해석하지 않으므로 이러한 쿼리에서는 오류가 발생합니다. 특히 별칭이 컬럼과 같은 이름일 때 문제가 가장 두드러집니다. 예시:

SELECT
    sum(value) AS value,
    avg(value)
FROM test

avg(value)는 어떤 value를 집계해야 할까요? 기본적으로 ClickHouse는 별칭을 우선적으로 해석하므로, 결과적으로 중첩 집계가 되는데 이는 대부분의 도구가 기대하는 동작이 아닙니다.

이 자체로 문제되는 경우는 드물지만, 일부 BI 도구는 컬럼 별칭을 재사용하는 서브쿼리가 포함된 쿼리를 생성합니다. 예를 들어 Power BI는 다음과 유사한 쿼리를 자주 생성합니다:

SELECT
    sum(C1) AS C1,
    count(C1) AS C2
FROM
(
    SELECT sum(value) AS C1
    FROM test
    GROUP BY group_index
) AS TBL

C1을 참조할 경우 다음과 같은 오류가 발생할 수 있습니다:

Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function sum(C1) AS C1 is found
inside another aggregate function in query. (ILLEGAL_AGGREGATION)

다른 데이터베이스는 일반적으로 이와 같은 방식으로 동일한 수준에서 별칭(별칭)을 확인하지 않고, 대신 C1을 서브쿼리의 컬럼으로 처리합니다. ClickHouse에서 유사한 동작을 유지하고 이러한 쿼리가 오류 없이 실행되도록 하기 위해 ODBC 드라이버는 prefer_column_name_to_alias를 활성화합니다.

대부분의 경우 이러한 설정을 활성화해도 문제가 되지 않습니다. 그러나 readonly 설정이 1로 지정된 사용자는 SELECT 쿼리에서도 어떤 설정도 변경할 수 없습니다. 이러한 사용자에게 SqlCompatibilitySettings를 활성화하면 오류가 발생합니다. 다음 섹션에서는 이 구성 매개변수가 읽기 전용 사용자에게도 작동하도록 하는 방법을 설명합니다.

​

읽기 전용 사용자가 SQL 호환성 설정을 사용할 수 있도록 하기

SqlCompatibilitySettings 매개변수가 활성화된 상태에서 ODBC 드라이버를 통해 ClickHouse에 연결하면, readonly 설정이 1로 지정된 사용자는 드라이버가 쿼리 설정을 변경하려고 시도하기 때문에 오류가 발생합니다:

Code: 164. DB::Exception: Cannot modify 'cast_keep_nullable' setting in readonly mode. (READONLY)
Code: 164. DB::Exception: Cannot modify 'prefer_column_name_to_alias' setting in readonly mode. (READONLY)

읽기 전용 모드의 사용자는 개별 SELECT 쿼리에서도 설정을 변경할 수 없으므로 이 문제가 발생합니다. 이 문제를 해결하는 방법은 여러 가지가 있습니다.

옵션 1. readonly를 2로 설정

가장 간단한 방법입니다. readonly를 2로 설정하면 사용자를 읽기 전용 모드로 유지하면서도 설정 변경이 가능해집니다.

ALTER USER your_odbc_user MODIFY SETTING
    readonly = 2

대부분의 경우 이 문제를 해결하는 가장 쉽고 권장되는 방법은 readonly를 2로 설정하는 것입니다. 이것으로 해결되지 않으면 두 번째 옵션을 사용하세요.

옵션 2. ODBC 드라이버가 설정하는 값에 맞게 사용자 설정 변경

이 방법도 간단합니다. 사용자 설정을 업데이트하여 ODBC 드라이버가 설정하려는 값과 미리 일치하게 하십시오.

ALTER USER your_odbc_user MODIFY SETTING
    cast_keep_nullable = 1,
    prefer_column_name_to_alias = 1

이 변경을 적용해도 ODBC 드라이버는 계속 설정 적용을 시도할 수 있지만, 값이 이미 일치하므로 실질적인 변경은 이루어지지 않으며 오류도 방지됩니다.

이 옵션 역시 간단하지만 유지 관리가 필요합니다. 최신 드라이버 버전에서는 설정 목록이 변경되거나 호환성을 위해 새로운 설정이 추가될 수 있습니다. ODBC 사용자에 이러한 설정을 하드코딩하면, ODBC 드라이버가 추가 설정을 적용하기 시작할 때마다 이를 업데이트해야 할 수 있습니다.