메인 콘텐츠로 건너뛰기

​
소개

ClickHouse Connect는 다양한 Python 애플리케이션과 상호 운용할 수 있도록 지원하는 핵심 데이터베이스 드라이버입니다.
  • 주요 인터페이스는 clickhouse_connect.driver 패키지의 Client 객체입니다. 이 핵심 패키지에는 ClickHouse 서버와 통신할 때 사용하는 여러 헬퍼 클래스와 유틸리티 함수, 그리고 삽입 및 SELECT 쿼리를 고급 방식으로 관리하기 위한 “Context” 구현도 포함되어 있습니다.
  • clickhouse_connect.datatypes 패키지는 실험적 기능을 제외한 모든 ClickHouse 데이터 타입에 대한 기본 구현과 하위 클래스를 제공합니다. 주요 기능은 ClickHouse 데이터를 ClickHouse “Native” 바이너리 컬럼형 포맷으로 직렬화 및 역직렬화하는 것이며, 이를 통해 ClickHouse와 클라이언트 애플리케이션 간에 가장 효율적으로 데이터를 전송할 수 있습니다.
  • clickhouse_connect.cdriver 패키지의 Cython/C 클래스는 가장 자주 사용되는 일부 직렬화 및 역직렬화를 최적화하여 순수 Python 구현보다 성능을 크게 향상합니다.
  • clickhouse_connect.cc_sqlalchemy 패키지에는 datatypes 및 dbi 패키지를 기반으로 구축된 SQLAlchemy 방언이 포함되어 있습니다. 이 구현은 JOIN이 포함된 SELECT 쿼리(INNER, LEFT OUTER, FULL OUTER, CROSS), WHERE 절, ORDER BY, LIMIT/OFFSET, DISTINCT 연산, WHERE 조건이 포함된 경량 DELETE SQL 문, 테이블 리플렉션, 기본적인 DDL 작업(CREATE TABLE, CREATE/DROP DATABASE) 등 SQLAlchemy Core 기능을 지원합니다. 고급 ORM 기능이나 고급 DDL 기능은 지원하지 않지만, ClickHouse의 OLAP 지향 데이터베이스에서 대부분의 분석 워크로드를 처리하기에 충분한 강력한 쿼리 기능을 제공합니다.
  • 코어 드라이버와 ClickHouse Connect SQLAlchemy 구현은 ClickHouse를 Apache Superset에 연결할 때 권장되는 메서드입니다. ClickHouse Connect 데이터베이스 연결 또는 clickhousedb SQLAlchemy 방언 연결 문자열(connection string)을 사용하십시오.
이 문서는 clickhouse-connect 릴리스 0.9.2 기준의 최신 내용입니다.
공식 ClickHouse Connect Python 드라이버는 ClickHouse 서버와의 통신에 HTTP 프로토콜을 사용합니다. 따라서 HTTP 로드 밸런서를 지원할 수 있고, 방화벽 및 프록시가 있는 엔터프라이즈 환경에서도 원활하게 동작합니다. 다만 네이티브 TCP 기반 프로토콜과 비교하면 압축률과 성능이 약간 낮고, 쿼리 취소와 같은 일부 고급 기능은 지원하지 않습니다. 사용 사례에 따라서는 네이티브 TCP 기반 프로토콜을 사용하는 Community Python drivers 중 하나를 사용하는 방안도 고려할 수 있습니다.

​
요구 사항 및 호환성

¹ClickHouse Connect는 표에 나열된 플랫폼에서 명시적으로 테스트되었습니다. 또한 우수한 cibuildwheel 프로젝트가 지원하는 모든 아키텍처에 대해, 테스트되지는 않았지만 C 최적화가 포함된 바이너리 휠도 빌드됩니다. 마지막으로 ClickHouse Connect는 순수 Python으로도 실행할 수 있으므로, 최신 Python 설치 환경이라면 소스 설치는 대부분의 환경에서 작동해야 합니다. ²SQLAlchemy 지원은 Core 기능(쿼리, 기본 DDL)으로 제한됩니다. ORM 기능은 지원되지 않습니다. 자세한 내용은 SQLAlchemy Integration Support 문서를 참조하십시오. ³ClickHouse Connect는 일반적으로 공식 지원 범위 밖의 버전에서도 잘 작동합니다.

​
설치

pip를 사용하여 PyPI에서 ClickHouse Connect를 설치합니다: pip install clickhouse-connect ClickHouse Connect는 소스 코드에서 직접 설치할 수도 있습니다:
  • GitHub 리포지토리를 git clone합니다.
  • (선택 사항) C/Cython 최적화를 빌드하고 활성화하려면 pip install cython을 실행합니다.
  • 프로젝트 루트 디렉터리로 이동한 다음 pip install .을 실행합니다.

​
지원 정책

문제를 보고하기 전에 ClickHouse Connect를 최신 버전으로 업데이트하십시오. 문제는 GitHub project에 등록해야 합니다. 향후 ClickHouse Connect 릴리스는 릴리스 시점에 적극적으로 지원되는 ClickHouse 버전과 호환되도록 설계되었습니다. 현재 적극적으로 지원되는 ClickHouse 서버 버전은 여기에서 확인할 수 있습니다. 어떤 ClickHouse 서버 버전을 사용해야 할지 확실하지 않다면 여기의 설명을 읽어보십시오. CI 테스트 매트릭스는 최신 LTS 릴리스 2개와 최신 안정 릴리스 3개를 대상으로 테스트합니다. 다만 HTTP 프로토콜과 ClickHouse 릴리스 간의 호환성을 깨뜨리는 변경이 거의 없기 때문에, ClickHouse Connect는 공식 지원 범위를 벗어난 서버 버전에서도 대체로 잘 작동합니다. 하지만 일부 고급 데이터 타입과의 호환성은 다를 수 있습니다.

​
기본 사용법

​
연결 정보를 확인합니다

HTTP(S)로 ClickHouse에 연결하려면 다음 정보가 필요합니다. ClickHouse Cloud 서비스의 연결 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있습니다. 서비스를 선택한 다음 Connect를 클릭하십시오. HTTPS를 선택하십시오. 연결 정보가 예시 curl 명령으로 표시됩니다. 자가 관리형 ClickHouse를 사용하는 경우 연결 정보는 ClickHouse 관리자가 설정합니다.

​
연결 설정

ClickHouse에 연결하는 방법에는 다음 두 가지 예시가 있습니다:
  • localhost에서 실행 중인 ClickHouse 서버에 연결합니다.
  • ClickHouse Cloud 서비스에 연결합니다.

​
ClickHouse Connect 클라이언트 인스턴스를 사용해 localhost에서 실행 중인 ClickHouse 서버에 연결합니다:

​
ClickHouse Connect 클라이언트 인스턴스를 사용하여 ClickHouse Cloud 서비스에 연결합니다:

앞서 확인한 연결 정보를 사용하세요. ClickHouse Cloud 서비스에는 TLS가 필요하므로 포트 8443을 사용하세요.

​
데이터베이스 사용하기

ClickHouse SQL 명령을 실행하려면 클라이언트의 command 메서드를 사용하세요:
배치 데이터를 삽입하려면 행과 값을 담은 2차원 배열과 함께 클라이언트 insert 메서드를 사용하십시오:
ClickHouse SQL을 사용해 데이터를 조회하려면 클라이언트 query 메서드를 사용하십시오:
마지막 수정일 2026년 7월 2일