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

> Python과 ClickHouse를 연결하기 위한 ClickHouse Connect 프로젝트 모음

# 소개

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](https://www.sqlalchemy.org/) 방언은 SQLAlchemy Core, 스키마 reflection, ClickHouse 전용 쿼리 절과 테이블 엔진, Alembic migration을 지원합니다. 기본적인 ORM 읽기와 삽입은 동작하지만, 이 방언은 완전한 unit-of-work ORM 동작보다는 분석 워크로드에 맞게 설계되었습니다.
* 핵심 드라이버와 [ClickHouse Connect SQLAlchemy](/ko/integrations/language-clients/python/sqlalchemy) 구현은 ClickHouse를 Apache Superset에 연결하는 데 권장되는 메서드입니다. `ClickHouse Connect` 데이터베이스 connection을 사용하거나 `clickhousedb` SQLAlchemy 방언 connection string을 사용하십시오.

이 문서는 clickhouse-connect 1.6.0 기준으로 최신 상태입니다. 0.15.x 또는 그 이전 버전에서 업그레이드하는 경우 [1.0 migration guide](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md)를 참조하십시오.

<Note>
  표준 ClickHouse Connect 클라이언트는 HTTP 인터페이스를 사용합니다. 따라서 HTTP load balancer, 프록시, 일반적인 엔터프라이즈 네트워크 제어를 지원할 수 있습니다. ClickHouse Connect에는 실험적인 in-process [chDB](#embedded-chdb-backend) 백엔드도 있습니다.
</Note>

<div id="requirements-and-compatibility">
  ## 요구 사항 및 호환성
</div>

| 구성 요소      | 지원 버전                                                           |
| ---------- | --------------------------------------------------------------- |
| Python     | 3.10\~3.14. 3.14t와 같은 free-threaded 빌드는 Experimental로 지원됩니다.    |
| ClickHouse | 현재 지원되는 ClickHouse 릴리스. 최신 LTS 및 안정 서버 릴리스를 대상으로 CI 테스트를 수행합니다. |
| SQLAlchemy | 1.4.40 이상, 3.0 미만                                               |
| Pandas     | 2.x 및 3.x                                                       |
| Polars     | 1.0 이상                                                          |
| aiohttp    | 3.9 이상                                                          |
| 플랫폼        | 각 Python 버전에 대해 게시된 wheel 아키텍처의 Linux, macOS, Windows           |

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

<div id="installation">
  ## 설치
</div>

pip를 사용하여 [PyPI](https://pypi.org/project/clickhouse-connect/)에서 ClickHouse Connect를 설치합니다:

```bash theme={null}
pip install clickhouse-connect
```

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

```bash theme={null}
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 리포지토리](https://github.com/ClickHouse/clickhouse-connect)를 `git clone`합니다.
* 프로젝트 루트 디렉터리로 이동한 다음 `pip install .`를 실행합니다. 빌드 시스템이 선택적 C 확장 기능을 컴파일할 수 있도록 Cython을 자동으로 설치합니다.

설치된 버전은 `clickhouse_connect.__version__`으로 확인할 수 있습니다.

<div id="support-policy">
  ## 지원 정책
</div>

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

<div id="basic-usage">
  ## 기본 사용법
</div>

<div id="gather-your-connection-details">
  ### 연결 정보를 확인합니다
</div>

HTTP(S)로 ClickHouse에 연결하려면 다음 정보가 필요합니다.

| 매개변수                      | 설명                                                         |
| ------------------------- | ---------------------------------------------------------- |
| `HOST` and `PORT`         | 일반적으로 TLS를 사용하는 경우 포트는 8443, TLS를 사용하지 않는 경우 8123입니다.      |
| `DATABASE NAME`           | 기본적으로 `default`라는 이름의 데이터베이스가 제공되며, 연결할 데이터베이스 이름을 사용하십시오. |
| `USERNAME` and `PASSWORD` | 기본 사용자 이름은 `default`입니다. 사용 사례에 맞는 사용자 이름을 사용하십시오.         |

ClickHouse Cloud 서비스의 연결 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있습니다.
서비스를 선택한 다음 **Connect**를 클릭하십시오.

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=119293dc89fd9bb8fa178d0bec957ecc" alt="ClickHouse Cloud 서비스 연결 버튼" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
  </Frame>
</div>

**HTTPS**를 선택하십시오. 연결 정보가 예시 `curl` 명령으로 표시됩니다.

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=16a5a08d3a2c44601d981b9ee5a75216" alt="ClickHouse Cloud HTTPS 연결 정보" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
  </Frame>
</div>

자가 관리형 ClickHouse를 사용하는 경우 연결 정보는 ClickHouse 관리자가 설정합니다.

<div id="establish-a-connection">
  ### 연결 설정
</div>

ClickHouse에 연결하는 방법에는 다음 두 가지 예시가 있습니다:

* localhost에서 실행 중인 ClickHouse 서버에 연결합니다.
* ClickHouse Cloud 서비스에 연결합니다.

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### ClickHouse Connect 클라이언트 인스턴스를 사용해 localhost에서 실행 중인 ClickHouse 서버에 연결합니다:
</div>

```python theme={null}
import clickhouse_connect

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

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-cloud-service">
  #### ClickHouse Connect 클라이언트 인스턴스를 사용하여 ClickHouse Cloud 서비스에 연결합니다:
</div>

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

```python theme={null}
import clickhouse_connect

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

<div id="interact-with-your-database">
  ### 데이터베이스 사용하기
</div>

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

```python theme={null}
client.command(
    "CREATE TABLE new_table "
    "(key UInt32, value String, metric Float64) "
    "ENGINE MergeTree ORDER BY key"
)
```

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

```python theme={null}
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` 메서드를 사용하세요:

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

client.close()
```

<div id="embedded-chdb-backend">
  ## 내장 chDB 백엔드
</div>

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

```python theme={null}
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 클라이언트 또는 외부 데이터는 지원하지 않습니다.