소개

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_sqlalchemy의 SQLAlchemy 방언은 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를 참조하십시오.

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

pip를 사용하여 PyPI에서 ClickHouse Connect를 설치합니다:

pip install clickhouse-connect

선택적 통합은 extras를 통해 설치할 수 있습니다:

pip install "clickhouse-connect[async]"      # Native asyncio client
pip install "clickhouse-connect[pandas]"     # Pandas
pip install "clickhouse-connect[arrow]"      # PyArrow
pip install "clickhouse-connect[polars]"     # Polars
pip install "clickhouse-connect[sqlalchemy]" # SQLAlchemy dialect
pip install "clickhouse-connect[alembic]"    # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]"       # Embedded chDB backend
pip install "clickhouse-connect[tzdata]"     # IANA time zones on minimal systems

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 서비스에 연결합니다.

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="localhost",
    username="default",
    password="password",
)

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="HOSTNAME.clickhouse.cloud",
    port=8443,
    username="default",
    password="your password",
)

ClickHouse SQL 명령을 실행하려면 클라이언트 command 메서드를 사용하세요:

client.command(
    "CREATE TABLE new_table "
    "(key UInt32, value String, metric Float64) "
    "ENGINE MergeTree ORDER BY key"
)

배치 데이터를 삽입하려면 행과 값으로 구성된 2차원 배열을 사용해 클라이언트 insert 메서드를 호출하십시오:

row1 = [1000, "String Value 1000", 5.233]
row2 = [2000, "String Value 2000", -107.04]
data = [row1, row2]
client.insert("new_table", data, column_names=["key", "value", "metric"])

ClickHouse SQL을 사용해 데이터를 조회하려면 클라이언트 query 메서드를 사용하세요:

result = client.query("SELECT max(key), avg(metric) FROM new_table")
print(result.result_rows)
# Output: [(2000, -50.9035)]

client.close()

실험 단계의 chDB 백엔드는 HTTP 서버 없이 Python 프로세스 내에서 ClickHouse 쿼리를 실행합니다. chdb extra를 설치한 후 interface="chdb" 또는 chdb:// DSN으로 백엔드를 선택하세요:

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT number FROM numbers(3)")
    print(result.result_rows)
    # Output: [(0,), (1,), (2,)]

기본 데이터베이스는 메모리에 있습니다. 영구 저장소를 사용하려면 path="/data/my_chdb"를 지정하거나 dsn="chdb:///data/my_chdb"를 사용하십시오. chDB는 프로세스당 하나의 엔진 경로만 허용합니다. async 클라이언트 또는 외부 데이터는 지원하지 않습니다.