Skip to main content
ClickHouse Connect는 다양한 Python 애플리케이션과 상호 운용되도록 지원하는 핵심 데이터베이스 드라이버입니다.
  • 주요 인터페이스는 clickhouse_connect.driver의 동기식 Client와 네이티브 aiohttp 기반 AsyncClient입니다. 드라이버 패키지는 쿼리 및 삽입 컨텍스트, 스트리밍 헬퍼, DB-API 지원, 그리고 더 낮은 수준의 HTTP 메서드도 제공합니다.
  • clickhouse_connect.datatypes 패키지는 ClickHouse 네이티브 바이너리 열 지향 포맷을 사용해 ClickHouse 타입을 serialize 및 deserialize합니다.
  • clickhouse_connect.driverc의 선택적 Cython 확장 기능은 일반적인 serialization, conversion, buffering 경로를 가속합니다. 확장 기능을 빌드할 수 없는 플랫폼에서는 pure Python 경로도 계속 사용할 수 있습니다.
  • 이 패키지는 PEP 561 타입 정보를 포함하므로, 하위 타입 검사기는 공개 드라이버, DB-API, SQLAlchemy 인터페이스에 대한 어노테이션을 사용할 수 있습니다.
  • clickhouse_connect.cc_sqlalchemySQLAlchemy 방언은 SQLAlchemy Core, 스키마 reflection, ClickHouse 전용 쿼리 절과 테이블 엔진, Alembic migration을 지원합니다. 기본적인 ORM 읽기와 삽입은 동작하지만, 이 방언은 완전한 unit-of-work ORM 동작보다는 분석 워크로드에 맞게 설계되었습니다.
  • 핵심 드라이버와 ClickHouse Connect SQLAlchemy 구현은 ClickHouse를 Apache Superset에 연결하는 데 권장되는 메서드입니다. ClickHouse Connect 데이터베이스 connection을 사용하거나 clickhousedb SQLAlchemy 방언 connection string을 사용하십시오.
이 문서는 clickhouse-connect 1.6.0 기준으로 최신 상태입니다. 0.15.x 또는 그 이전 버전에서 업그레이드하는 경우 1.0 migration guide를 참조하십시오.
표준 ClickHouse Connect 클라이언트는 HTTP 인터페이스를 사용합니다. 따라서 HTTP load balancer, 프록시, 일반적인 엔터프라이즈 네트워크 제어를 지원할 수 있습니다. ClickHouse Connect에는 실험적인 in-process chDB 백엔드도 있습니다.

요구 사항 및 호환성

이 package에는 가능한 경우 컴파일된 wheel이 포함되며, Cython 확장 기능을 빌드할 수 없으면 pure Python 구현으로 대체됩니다. PyArrow는 Python 3.10~3.14에서 지원됩니다. Python 3.14에는 PyArrow 22 이상이 필요합니다.

설치

pip를 사용하여 PyPI에서 ClickHouse Connect를 설치합니다:
선택적 통합은 extras를 통해 설치할 수 있습니다:
ClickHouse Connect는 소스 코드에서 직접 설치할 수도 있습니다:
  • GitHub 리포지토리git clone합니다.
  • 프로젝트 루트 디렉터리로 이동한 다음 pip install .를 실행합니다. 빌드 시스템이 선택적 C 확장 기능을 컴파일할 수 있도록 Cython을 자동으로 설치합니다.
설치된 버전은 clickhouse_connect.__version__으로 확인할 수 있습니다.

지원 정책

이슈를 보고하기 전에 ClickHouse Connect를 최신 릴리스로 업데이트하십시오. 이슈는 GitHub 프로젝트에 등록하십시오. ClickHouse Connect는 각 드라이버 릴리스 시점에 현재 활발히 지원되는 ClickHouse 릴리스를 대상으로 합니다. 이전 서버 버전에서도 작동하는 경우가 많지만, 최신 데이터 타입과 프로토콜 기능을 사용하려면 더 새로운 서버가 필요할 수 있습니다.

기본 사용법

연결 정보를 확인합니다

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 메서드를 사용하세요:

내장 chDB 백엔드

실험 단계의 chDB 백엔드는 HTTP 서버 없이 Python 프로세스 내에서 ClickHouse 쿼리를 실행합니다. chdb extra를 설치한 후 interface="chdb" 또는 chdb:// DSN으로 백엔드를 선택하세요:
기본 데이터베이스는 메모리에 있습니다. 영구 저장소를 사용하려면 path="/data/my_chdb"를 지정하거나 dsn="chdb:///data/my_chdb"를 사용하십시오. chDB는 프로세스당 하나의 엔진 경로만 허용합니다. async 클라이언트 또는 외부 데이터는 지원하지 않습니다.
마지막 수정일 2026년 8월 14일