> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ClickHouse Connect 드라이버 API # ClickHouse Connect 드라이버 API 선택적 매개변수가 많은 클라이언트 팩터리와 메서드에서는 키워드 인수를 사용하십시오. *여기에 문서화되지 않은 메서드는 API의 일부로 간주되지 않으며, 제거되거나 변경될 수 있습니다.*

클라이언트 초기화

동기 `Client`를 생성하려면 `clickhouse_connect.get_client`를 사용하십시오. 네이티브 `AsyncClient`를 생성하려면 `async` extra를 설치한 후 `clickhouse_connect.get_async_client`를 await하십시오.

연결 인수

| 매개변수 | 유형 | 기본값 | 설명 | | - | - | - | - | | `interface` | str | `"http"` | `"http"` 또는 `"https"`입니다. 동기 팩터리에서는 실험적 `"chdb"` backend도 사용할 수 있습니다. | | `host` | str | `"localhost"` | ClickHouse 서버의 호스트명 또는 IP 주소입니다. | | `port` | int 또는 None | `8123` or `8443` | HTTP는 기본적으로 8123, HTTPS는 8443을 사용합니다. `None`을 전달하면 기본 포트를 사용하도록 요청합니다. | | `username` | str 또는 None | `"default"` | ClickHouse 사용자 이름입니다. `user` 및 `user_name` 별칭도 사용할 수 있습니다. | | `password` | str | `""` | `username`의 비밀번호입니다. 사용자 이름/비밀번호 인증과 토큰 인증은 함께 사용하지 마십시오. | | `access_token` | str 또는 None | `None` | ClickHouse Cloud JWT 액세스 토큰입니다. `token_provider` 및 사용자 이름/비밀번호 인증과는 상호 배타적입니다. | | `token_provider` | callable 또는 None | `None` | JWT를 처음과 인증이 거부된 후에 제공하는 호출 가능 객체입니다. 비동기 provider는 `get_async_client`와 함께 사용할 수 있습니다. | | `database` | str 또는 None | 사용자 기본값 | 기본 데이터베이스입니다. `None`을 전달하면 사용자의 서버 기본값을 요청합니다. | | `secure` | bool 또는 str | `False` | HTTPS/TLS를 활성화합니다. `interface="https"`를 지정해도 HTTPS가 선택되며, `interface`를 설정하지 않은 경우에는 포트 443 또는 8443을 사용해도 마찬가지입니다. | | `dsn` | str 또는 None | `None` | 연결 URL입니다. 명시적으로 지정한 키워드 인수는 DSN에서 파싱된 값보다 우선합니다. 자격 증명과 데이터베이스 이름에 포함된 예약 문자는 퍼센트 인코딩해야 합니다. | | `settings` | dict 또는 None | `None` | 클라이언트가 보내는 모든 요청에 적용되는 ClickHouse 설정입니다. | | `headers` | dict 또는 None | `None` | 클라이언트 초기화를 포함한 모든 요청에 적용되는 HTTP headers입니다. 사용자 headers는 driver 기본값 다음에 적용되며, 이를 재정의할 수 있습니다. | | `compress` | bool 또는 str | `True` | 압축을 활성화하거나 `"lz4"`, `"zstd"`, `"br"`, `"gzip"` 중 하나를 선택합니다. [Compression](/ko/integrations/language-clients/python/additional-options#compression)을 참조하세요. | | `query_limit` | int | `0` | 적용 가능한 쿼리에 기본 행 수 제한이 추가됩니다. 0은 무제한을 의미합니다. 큰 결과는 모두 메모리에 구체화하지 말고 스트리밍하십시오. | | `query_retries` | int | `2` | 재시도 가능한 읽기 실패에 허용되는 재시도 한도입니다. 명령과 삽입 작업은 다시 실행할 경우 부수 효과가 중복될 수 있으므로 일반적으로 재시도하지 않습니다. | | `connect_timeout` | 동기는 int, 비동기는 float | `10` | 새 연결을 수립할 때 적용되는 초 단위 타임아웃입니다. 연결 풀의 빈 슬롯을 기다리는 시간은 포함되지 않습니다. 비동기 클라이언트는 소수점 이하 초 단위 값도 허용합니다. | | `send_receive_timeout` | 동기는 int, 비동기는 float | `300` | 초 단위의 소켓 읽기 타임아웃입니다. 비동기 클라이언트는 소수점 이하 초 단위 값도 허용합니다. | | `client_name` | str or None | `None` | `system.query_log`에서 식별할 수 있도록 HTTP User-Agent 앞에 추가되는 접두사입니다. | | `session_id` | str 또는 None | 동기용으로 생성 | 명시적으로 지정하는 ClickHouse session ID입니다. 동기 클라이언트는 기본적으로 이를 생성하지만, async 클라이언트는 생성하지 않습니다. | | `autogenerate_session_id` | bool 또는 None | 동기에서는 전역 설정, 비동기에서는 `False` | 자동 session ID 생성을 재정의합니다. session 상태가 필요하지 않다면 동시 작업에서 공유되는 클라이언트에서는 이 기능을 비활성화하십시오. | | `autogenerate_query_id` | bool 또는 None | 전역 설정, `True` | 자동 UUID 쿼리 ID 생성 동작을 재정의합니다. | | `http_proxy` | str 또는 None | 환경/기본값 | 클라이언트별 HTTP 프록시 주소. | | `https_proxy` | str 또는 None | 환경/기본값 | 클라이언트별 HTTPS 프록시 주소. | | `pool_mgr` | `urllib3.PoolManager` 또는 None | 프로세스 단위로 공유 | 동기식 클라이언트에만 사용하는 사용자 지정 풀 관리자. | | `tz_source` | str or None | `"auto"` | 시간대 메타데이터가 없는 컬럼에 사용할 폴백 시간대 소스: `"auto"`, `"server"`, 또는 `"local"`. | | `tz_mode` | str or None | `"naive_utc"` | UTC 결과 처리 정책: `"naive_utc"`, `"aware"`, 또는 `"schema"`입니다. [시간대](/ko/integrations/language-clients/python/advanced-querying#time-zones)를 참조하십시오. | | `show_clickhouse_errors` | bool, Boolean 문자열, `"scrub"`, 또는 None | `True` | 서버 오류, 전송 오류 및 스트림 도중 발생하는 `StreamFailureError`의 `str(exc)`를 제어합니다. `True`이면 요청 URL과 서버 버전 정보가 포함됩니다. `"scrub"`은 SQL 오류 텍스트와 심볼릭 이름은 유지하지만 호스트/URL 및 `(version ...)` 정보는 제거합니다. `False`는 일반 메시지를 반환합니다(서버 오류에서도 `code`는 설정됨). Boolean 문자열도 사용할 수 있습니다. 그 밖의 문자열은 `ProgrammingError`를 발생시킵니다. 전송 오류의 경우 `__cause__`와 트레이스백에는 원래 전송 예외가 계속 포함됩니다. | | `proxy_path` | str | `""` | 프록시를 통해 라우팅할 때 서버 URL에 추가되는 경로 접두사입니다. | | `form_encode_query_params` | bool | `False` | 쿼리 매개변수를 항상 form-encoded 요청 본문에 넣습니다. 이 값이 false여도 큰 비바이너리 매개변수 페이로드는 자동으로 이동됩니다. | | `native_codec` | str 또는 None | 전역 설정, `"python"` | 클라이언트가 관리하는 Native 형식 트래픽에 사용하는 실험적 코덱: `"python"`, `"rust"`, 또는 `"rust_strict"`. Rust 값을 사용하려면 `clickhouse-connect-core` 휠이 필요합니다. [Rust 코덱](/ko/integrations/language-clients/python/rust-codec)을 참조하십시오. | | `rename_response_column` | str 또는 None | `None` | 컬럼 이름 변경 방식: `"remove_prefix"`, `"to_camelcase"`, `"to_camelcase_without_prefix"`, `"to_underscore"`, 또는 `"to_underscore_without_prefix"`. | 동기 및 비동기 HTTP 팩토리는 모두 다음 클라이언트 옵션에 대해 DSN 쿼리 매개변수 또는 `generic_args`로 전달된 문자열 값을 변환합니다. `connect_timeout`, `send_receive_timeout`, `query_limit`, `query_retries`는 위에 표시된 숫자 타입으로, `autogenerate_query_id`, `autogenerate_session_id`, `form_encode_query_params`는 불리언(boolean)으로 변환됩니다. 이러한 옵션에 유효하지 않은 문자열 값을 지정하면 `ProgrammingError`가 발생합니다. 비동기 팩토리는 aiohttp 연결 풀을 구성하기 위한 `connector_limit=100`, `connector_limit_per_host=20`, `keepalive_timeout=30.0`도 허용합니다. 이러한 값은 직접 키워드 인수, DSN 쿼리 매개변수 또는 `generic_args`를 통해 전달하십시오. `generic_args`는 내부적으로 SQLAlchemy `connect_args`에 사용됩니다. 이러한 커넥터 옵션의 문자열 값은 문서에 명시된 숫자 타입으로 변환되며, 유효하지 않은 문자열 값을 지정하면 `ProgrammingError`가 발생합니다. 우선순위는 `None`이 아닌 명시적 키워드 인수가 가장 높고, 그다음 `generic_args`, DSN 순입니다. `pool_mgr`는 허용되지 않습니다. 동기 chDB 백엔드는 `path`와 `chdb_options`를 허용합니다. 자세한 내용은 [내장 chDB 백엔드](#embedded-chdb-backend)를 참조하십시오.

HTTPS/TLS 인수

| 매개변수 | 유형 | 기본값 | 설명 | | - | - | - | - | | `verify` | bool or str | `True` | 서버 인증서와 호스트명을 검증합니다. `verify="proxy"`는 프록시 TLS 모드를 활성화합니다. | | `ca_cert` | str or None | `None` | CA 번들 경로입니다. `certifi` package와 함께 제공되는 번들을 선택하려면 `"certifi"`를 사용하십시오. | | `client_cert` | str or None | `None` | PEM 클라이언트 인증서입니다. 필요한 경우 중간 인증서도 포함합니다. | | `client_cert_key` | str or None | `None` | 키가 `client_cert`에 포함되지 않은 경우 사용할 private key 경로입니다. | | `server_host_name` | str or None | `None` | 터널 또는 Private Endpoint를 사용하는 경우처럼 `host`와 다를 때 사용할 TLS 인증서/SNI 호스트명입니다. | | `tls_mode` | str or None | `None` | `"mutual"`은 ClickHouse 상호 TLS 인증을 사용합니다. `"proxy"`와 `"strict"`는 ClickHouse 인증서 인증 헤더를 활성화하지 않고 TLS 계층에서 인증서를 전송합니다. 기본값 `None`은 클라이언트 인증서가 제공되면 `"mutual"`처럼 동작합니다. |

설정 인수

마지막으로, `get_client`의 `settings` 인수는 각 클라이언트 요청마다 추가 ClickHouse 설정을 서버에 전달하는 데 사용됩니다. 대부분의 경우 *readonly*=*1* 권한을 가진 사용자는 쿼리와 함께 전송된 설정을 변경할 수 없으므로, ClickHouse Connect는 최종 요청에서 이러한 설정을 제외하고 경고를 기록합니다. 다음 설정은 ClickHouse Connect에서 사용하는 HTTP 쿼리/세션에만 적용되며, 일반적인 ClickHouse 설정으로 문서화되어 있지 않습니다. | 설정 | 설명 | | - | - | | `buffer_size` | 서버 측 HTTP 응답 버퍼 크기(바이트 단위)입니다. | | `session_id` | 관련 요청을 연결하는 데 사용하는 세션 ID입니다. 임시 테이블 및 세션 상태에 필요합니다. | | `compress` | 서버에 HTTP 응답을 압축하도록 요청합니다. 일반적으로 클라이언트 압축 옵션으로 관리됩니다. | | `decompress` | 서버에 요청 본문을 압축 해제하도록 지시합니다. 사전 압축된 raw 삽입에 사용됩니다. | | `quota_key` | 요청에 연결된 쿼터 키입니다. | | `session_check` | 세션이 존재하는지 확인하도록 서버에 요청합니다. | | `session_timeout` | 세션 비활성 timeout 시간(초)입니다. | | `wait_end_of_query` | 서버에서 전체 응답을 버퍼링합니다. 클라이언트는 비스트리밍 요약 정보가 필요할 때 이 값을 설정합니다. | | `query_id` | 요청에 대한 명시적 쿼리 ID입니다. | | `client_protocol_version` | 네이티브 포맷 클라이언트 프로토콜 capability 수준입니다. 일반적으로 자동으로 협상됩니다. | | `role` | 요청/세션에 사용할 ClickHouse 역할(Role)입니다. | 각 쿼리와 함께 전송할 수 있는 다른 ClickHouse 설정은 [ClickHouse 문서](/ko/reference/settings/session-settings)를 참조하십시오.

클라이언트 생성 예시

* 매개변수를 지정하지 않으면 ClickHouse Connect 클라이언트는 `localhost`의 기본 HTTP 포트에 `default` 사용자로 비밀번호 없이 연결됩니다: ```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() print(client.server_version) ``` * 보안(HTTPS)을 사용하는 외부 ClickHouse 서버에 연결 ```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client( host="play.clickhouse.com", secure=True, port=443, username="play", password="clickhouse", ) print(client.command("SELECT timezone()")) ``` * 세션 ID와 기타 사용자 지정 연결 매개변수, ClickHouse 설정을 사용해 연결합니다. ```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client( host="play.clickhouse.com", username="play", password="clickhouse", port=443, secure=True, session_id="example_session_1", connect_timeout=15, database="github", settings={"distributed_ddl_task_timeout": 300}, ) print(client.database) # Output: github ```

내장 chDB 백엔드

실험적인 인프로세스 chDB 백엔드를 사용하려면 `clickhouse-connect[chdb]`를 설치하십시오. 이 백엔드는 동기식 클라이언트의 쿼리, 삽입, 스트리밍 및 Arrow 메서드를 제공합니다: ```python theme={null} import clickhouse_connect with clickhouse_connect.get_client(interface="chdb") as client: result = client.query("SELECT sum(number) FROM numbers(10)") print(result.first_row) # Output: (45,) ``` 기본값은 인메모리 데이터베이스입니다. 영구 저장소를 사용하려면 `path="/data/my_chdb"`를 지정하거나 `dsn="chdb:///data/my_chdb"`를 사용하십시오. 백엔드는 프로세스당 하나의 엔진 경로만 허용하며 `get_async_client` 또는 외부 데이터를 지원하지 않습니다.

클라이언트 수명 주기와 모범 사례

ClickHouse Connect 클라이언트를 생성하는 작업은 연결을 설정하고, 서버 메타데이터를 가져오고, 설정을 초기화하는 과정이 포함되므로 비용이 많이 드는 작업입니다. 최적의 성능을 위해 다음 모범 사례를 따르십시오:

핵심 원칙

* **클라이언트 재사용**: 애플리케이션 시작 시 클라이언트를 한 번만 생성하고, 애플리케이션이 실행되는 동안 계속 재사용합니다 * **빈번한 생성 방지**: 각 쿼리나 요청마다 새 클라이언트를 생성하지 마십시오 * **적절한 정리**: 종료할 때는 연결 풀 리소스를 해제할 수 있도록 항상 클라이언트를 닫으십시오 * **가능하면 공유**: 단일 클라이언트는 연결 풀을 통해 많은 동시 쿼리를 처리할 수 있습니다(아래의 스레딩 참고 사항 참조)

기본 패턴

단일 클라이언트를 재사용하세요: ```python theme={null} import clickhouse_connect # Create once at startup client = clickhouse_connect.get_client( host="my-host", username="default", password="password", ) # Reuse for all queries for i in range(1000): result = client.query("SELECT count() FROM users") # Close on shutdown client.close() ``` 클라이언트를 반복해서 생성하지 마세요: ```python theme={null} # BAD: Creates 1000 clients with expensive initialization overhead for i in range(1000): client = clickhouse_connect.get_client( host="my-host", username="default", password="password", ) result = client.query("SELECT count() FROM users") client.close() ```

멀티스레드 애플리케이션

세션 ID를 사용하는 경우 클라이언트 인스턴스는 **스레드 안전하지 않습니다**. 기본적으로 클라이언트에는 자동 생성된 세션 ID가 있습니다. 하나의 클라이언트에서 동일한 세션으로 쿼리를 동시에 실행할 때 클라이언트가 로컬에서 중첩을 감지하면 `ProgrammingError`가 발생합니다. 이름이 지정된 세션의 상태와 서버 측 세션 중첩 검사는 개별 ClickHouse 서버 프로세스 내에서만 유효합니다. 따라서 ClickHouse Cloud나 로드 밸런싱을 사용하는 기타 배포 환경에서는 고정된 `session_id`가 분산 상태나 분산 뮤텍스 역할을 하지 않습니다. 스레드 간에 클라이언트를 안전하게 공유하려면: ```python theme={null} import clickhouse_connect import threading # Option 1: Disable sessions (recommended for shared clients) client = clickhouse_connect.get_client( host="my-host", username="default", password="password", autogenerate_session_id=False, ) def worker(thread_id): # All threads can now safely use the same client result = client.query(f"SELECT {thread_id}") print(f"Thread {thread_id}: {result.result_rows[0][0]}") threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)] for t in threads: t.start() for t in threads: t.join() client.close() ``` **세션 대신:** 세션이 필요하다면(예: 임시 테이블 사용 시) 스레드마다 별도의 클라이언트를 생성하십시오: ```python theme={null} def worker(thread_id): # Each thread gets its own client with isolated session client = clickhouse_connect.get_client( host="my-host", username="default", password="password", ) client.command("CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory") # ... use temp table ... client.close() ```

올바른 정리

종료 시에는 항상 클라이언트를 닫으십시오. `client.close()`는 클라이언트가 자체 풀 관리자(pool manager)를 소유한 경우에만(예: 사용자 지정 TLS/프록시 옵션으로 생성된 경우) 클라이언트를 정리하고 풀링된 HTTP 연결을 닫습니다. 이 점에 유의하십시오. 기본 공유 풀에서는 `client.close_connections()`를 사용해 소켓을 미리 정리하십시오. 그렇지 않으면 연결은 idle 만료 시점이나 프로세스 종료 시 자동으로 회수됩니다. ```python theme={null} client = clickhouse_connect.get_client( host="my-host", username="default", password="password", ) try: result = client.query("SELECT 1") finally: client.close() ``` 또는 컨텍스트 관리자를 사용하세요: ```python theme={null} with clickhouse_connect.get_client( host="my-host", username="default", password="password", ) as client: result = client.query("SELECT 1") ```

여러 클라이언트를 사용해야 하는 경우

여러 클라이언트는 다음과 같은 경우에 적합합니다. * **서로 다른 서버**: ClickHouse 서버 또는 클러스터마다 클라이언트를 1개씩 사용 * **서로 다른 자격 증명**: 서로 다른 사용자 또는 접근 수준별로 별도의 클라이언트 사용 * **서로 다른 데이터베이스**: 여러 데이터베이스에서 작업해야 하는 경우 * **격리된 세션**: 임시 테이블 또는 세션별 설정을 위해 별도의 세션이 필요한 경우 * **스레드별 격리**: 스레드마다 독립적인 세션이 필요한 경우(위 예시 참조)

공통 메서드 인수

여러 클라이언트 메서드는 공통 `parameters` 및 `settings` 인수 중 하나 또는 둘 다를 사용합니다. 이러한 키워드 인수는 아래에서 설명합니다.

매개변수 인수

ClickHouse Connect Client의 `query*` 및 `command` 메서드는 Python 표현식을 ClickHouse 값 표현식에 바인딩하는 데 사용하는 선택적 키워드 인수 `parameters`를 지원합니다. 바인딩은 두 가지 방식으로 사용할 수 있습니다.

서버 측 바인딩

ClickHouse는 쿼리 값에 대해 [서버 측 바인딩](/ko/concepts/features/interfaces/client#cli-queries-with-parameters)을 지원합니다. 바인딩된 값은 쿼리와 별도로 HTTP 매개변수로 전송됩니다. ClickHouse Connect는 `{:}` 형식의 표현식이 감지되면 이 모드를 사용합니다. 값은 Python 딕셔너리로 전달하십시오. 매개변수 이름은 ClickHouse ASCII BareWord 이름이어야 합니다. 서버에서 허용하는 경우 드라이버는 `{$tenant_id:String}`처럼 이름의 시작, 내부 또는 끝에 있는 `$`를 허용합니다. `bytes`, `bytearray` 또는 `memoryview`와 같은 버퍼 값을 가지며 `$`로 시작하고 끝나는 딕셔너리 키는 ClickHouse Connect의 원시 바이너리 매개변수 규칙을 위해 예약됩니다. 이러한 키를 비바이너리 서버 측 매개변수에 사용하는 경우 단일 `{name:Type}` 플레이스홀더만 사용하십시오. 반복되는 `$tag$` 이름은 ClickHouse에서 Heredoc 마커로 파싱될 수 있습니다. 널 허용 값에는 Python `None`을 사용하십시오. 중첩된 `None` 값은 `Array` 및 `Tuple` 매개변수 내부와 `dict_parameter_format`이 `"map"`으로 설정된 경우 `Map` 리터럴 내부에서 지원됩니다. * Python 딕셔너리, DateTime 값, 문자열 값을 사용하는 서버 측 바인딩 ```python theme={null} import datetime my_date = datetime.datetime(2022, 10, 1, 15, 20, 5) parameters = { "table": "my_table", "v1": my_date, "v2": "a string with a single quote'", } client.query( "SELECT * FROM {table:Identifier} " "WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}", parameters=parameters, ) ``` 이는 다음과 같습니다: ```sql theme={null} SELECT * FROM my_table WHERE date >= '2022-10-01 15:20:05' AND string ILIKE 'a string with a single quote\'' ``` 서버 측 바인딩은 `SELECT` 쿼리와 `INSERT ... VALUES` SQL 문에서 사용할 수 있습니다. 대량의 일반 삽입 배치에는 `Client.insert`를 사용하는 것이 좋습니다.

클라이언트 측 바인딩

ClickHouse Connect는 클라이언트 측 매개변수 바인딩도 지원하며, 이를 통해 템플릿 기반 SQL 쿼리를 더 유연하게 생성할 수 있습니다. 클라이언트 측 바인딩에서는 `parameters` 인수가 딕셔너리 또는 시퀀스여야 합니다. 클라이언트 측 바인딩은 매개변수 치환을 위해 Python의 ["printf" 스타일](https://docs.python.org/3/library/stdtypes.html#old-string-formatting) 문자열 포맷팅을 사용합니다. 서버 측 바인딩과 달리 클라이언트 측 바인딩은 데이터베이스, 테이블, 컬럼 이름과 같은 데이터베이스 식별자에는 사용할 수 없습니다. Python 스타일 포맷팅은 서로 다른 문자열 타입을 구분하지 못하며, 이러한 값은 서로 다른 방식으로 포맷팅해야 하기 때문입니다(데이터베이스 식별자에는 backticks 또는 큰따옴표를 사용하고, 데이터 값에는 작은따옴표를 사용). * Python 딕셔너리, DateTime 값, 문자열 이스케이프를 사용하는 예시 ```python theme={null} import datetime my_date = datetime.datetime(2022, 10, 1, 15, 20, 5) parameters = {"v1": my_date, "v2": "a string with a single quote'"} client.query( "SELECT * FROM my_table " "WHERE date >= %(v1)s AND string ILIKE %(v2)s", parameters=parameters, ) ``` 그러면 서버에서 다음 쿼리가 생성됩니다: ```sql theme={null} SELECT * FROM my_table WHERE date >= '2022-10-01 15:20:05' AND string ILIKE 'a string with a single quote\'' ``` * Python 시퀀스(Tuple), Float64, IPv4Address 사용 예시 ```python theme={null} import ipaddress parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe)) client.query( "SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s", parameters=parameters, ) ``` 그러면 서버에서 다음 쿼리가 생성됩니다: ```sql theme={null} SELECT * FROM some_table WHERE metric >= 35200.44 AND ip_address = '68.61.4.254' ``` Datetime 바인딩은 naive 값을 wall time으로 처리합니다. 클라이언트는 naive `datetime`을 그대로 포맷합니다. ClickHouse는 `{dt:DateTime('Europe/Berlin')}`와 같은 서버 측 플레이스홀더에 선언된 시간대를 사용해 이를 해석하고, 없으면 설정된 `session_timezone`을 사용하며, 그마저 없으면 서버 시간대를 사용합니다. 시간대 인식 `datetime`은 플레이스홀더에 시간대가 선언되어 있으면 해당 시간대로 변환되고, 그렇지 않으면 연결 시 보고된 서버 시간대로 변환됩니다. `session_timezone` 설정이 보고된 서버 시간대와 다르면, 시간대 인식 값에서 의도한 시점을 유지하도록 플레이스홀더에 시간대를 선언하십시오. 이전 호스트 로컬 변환과의 임시 호환성을 위해 매개변수를 바인딩하기 전에 `common.set_setting("naive_datetime_binding", "legacy")`를 설정하십시오. 시점을 보존하려면 `datetime` 값을 매개변수로 전달하기 전에 의도한 `tzinfo`를 지정하십시오. `client.insert`를 통해 `DateTime` 또는 `DateTime64` 컬럼에 삽입할 때는 기본적으로 naive `datetime` 값을 프로세스 로컬 시간대로 해석합니다. 컬럼 시간대의 wall time으로 해석하려면 전역 `naive_datetime_insert` 설정을 `"server"`로 지정하십시오. 컬럼에 시간대가 없으면 서버 시간대를 사용합니다. [시간대 정보가 없는 datetime 객체](/ko/integrations/language-clients/python/advanced-inserting#timezone-naive-datetime-objects)를 참조하십시오. `Date` 및 `Date32` 컬럼에 네이티브 방식으로 삽입할 때는 시간대 변환 없이 Python `datetime` 값 자체의 달력 날짜를 사용합니다. 삽입과 쿼리 매개변수 모두에서 동일한 달력 날짜가 필요하면 `value.date()`를 명시적으로 전달하십시오. [Date 및 Date32 값](/ko/integrations/language-clients/python/advanced-inserting#date-and-date32-values)을 참조하십시오. 서버 측 `{value:DateTime64(precision)}` 플레이스홀더의 경우 선언된 유형이 `Array` 및 `Tuple` 힌트 내부를 포함해 초 미만 정밀도를 자동으로 유지합니다. 클라이언트 측 `%s` 바인딩에는 선언된 유형이 없습니다. 초 미만 정밀도로 렌더링해야 하는 경우 `datetime`을 `DT64Param`으로 감싸십시오: ```python theme={null} from datetime import datetime from clickhouse_connect.driver.binding import DT64Param query = "SELECT toDateTime64(%s, 6)" parameters = [DT64Param(datetime.now())] client.query(query, parameters=parameters) ``` 이전 버전과의 호환성을 위해, 딕셔너리 매개변수 이름이 `_64`로 끝나는 경우에도 쿼리에 정확히 그 접미사가 붙은 이름이 없으면 DateTime64 포맷팅을 요청합니다. `datetime.time` 또는 `datetime.timedelta` 매개변수는 두 바인딩 스타일 모두에서, 그리고 `Array` 및 `Tuple` 값 내부에서 ClickHouse `Time` 및 `Time64` 컬럼용 `[-]HH:MM:SS[.ffffff]` 리터럴로 포맷됩니다. 클라이언트가 따옴표를 추가하므로 쿼리에서 플레이스홀더를 따옴표로 묶지 마십시오. `timedelta`는 음수일 수 있으며 24시간을 초과할 수 있습니다. pandas `Timedelta`는 나노초를 유지하며 `Time64(9)`에 대해 9자리 소수 부분으로 포맷됩니다. ClickHouse `Time`에는 시간대가 없으므로 시간대 인식 `time`의 시간대 정보는 무시됩니다.

설정 인수

주요 ClickHouse Connect Client의 "insert" 및 "select" 메서드는 모두 포함된 SQL 문에 대해 ClickHouse 서버 [사용자 설정](/ko/reference/settings/session-settings)을 전달할 수 있도록 선택적 `settings` 키워드 인수를 지원합니다. `settings` 인수는 딕셔너리여야 합니다. 각 항목은 ClickHouse 설정 이름과 해당 값으로 이루어져야 합니다. 값은 서버로 쿼리 매개변수로 전송될 때 문자열로 변환된다는 점에 유의하십시오. 클라이언트 수준 설정과 마찬가지로, ClickHouse Connect는 서버가 *readonly*=*1*로 표시한 설정을 관련 로그 메시지와 함께 모두 제외합니다. ClickHouse HTTP 인터페이스를 통한 쿼리에만 적용되는 설정은 항상 유효합니다. 이러한 설정은 `get_client` [API](#settings-argument)에서 설명합니다. ClickHouse 설정 사용 예시: ```python theme={null} settings = { "merge_tree_min_rows_for_concurrent_read": 65535, "session_id": "session_1234", "use_skip_indexes": False, } client.query( "SELECT event_type, sum(timeout) " "FROM event_errors WHERE event_time > '2022-08-01'", settings=settings, ) ```

Client `command` 메서드

표 형식의 데이터셋을 반환하지 않는 SQL 문이나, 단일 원시 값 또는 단일 행을 반환하는 쿼리에는 `Client.command`를 사용합니다. 응답에 따라 문자열, 정수, 문자열 시퀀스 또는 `QuerySummary`를 반환합니다. 빈 결과 집합을 생성하는 읽기 작업은 빈 문자열을 반환합니다. | 매개변수 | Type | Default | Description | | - | - | - | - | | cmd | str | *Required* | 단일 값 또는 값으로 이루어진 단일 행을 반환하는 ClickHouse SQL 문입니다. | | parameters | dict or sequence | *None* | [매개변수 설명](#parameters-argument)을 참조하십시오. | | data | str or bytes | *None* | 명령과 함께 POST 본문으로 포함할 수 있는 선택적 데이터입니다. | | settings | dict | *None* | [설정 설명](#settings-argument-1)을 참조하십시오. | | use\_database | bool | True | 클라이언트 데이터베이스(클라이언트 생성 시 지정됨)를 사용합니다. False이면 명령은 연결된 사용자의 기본 ClickHouse 서버 데이터베이스를 사용합니다. | | external\_data | ExternalData | *None* | 쿼리와 함께 사용할 파일 또는 바이너리 데이터가 포함된 `ExternalData` 객체입니다. [고급 쿼리(외부 데이터)](/ko/integrations/language-clients/python/advanced-querying#external-data)를 참조하십시오. | | transport\_settings | dict | *None* | 이 요청에 포함할 HTTP 헤더의 선택적 딕셔너리입니다. 각 키-값 쌍은 HTTP 헤더로 추가됩니다(예: `{'X-Custom-Header': 'value'}`). 프록시 인증, 요청 추적 또는 중간 인프라에 필요한 헤더를 전달할 때 유용합니다. |

명령 예시

DDL 문

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Create a table. A successful DDL returns QuerySummary. summary = client.command( "CREATE TABLE test_command " "(col_1 String, col_2 DateTime) " "ENGINE MergeTree ORDER BY tuple()" ) print(summary.query_id()) # Show table definition result = client.command("SHOW CREATE TABLE test_command") print(result) # Output: # CREATE TABLE default.test_command # ( # `col_1` String, # `col_2` DateTime # ) # ENGINE = MergeTree # ORDER BY tuple() # Drop table client.command("DROP TABLE test_command") ```

단일 값을 반환하는 간단한 쿼리

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Single value result count = client.command("SELECT count() FROM system.tables") print(count) # Server version version = client.command("SELECT version()") print(version) ```

매개변수를 사용하는 명령

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # 클라이언트 측 매개변수 사용 table_name = "system" result = client.command( "SELECT count() FROM system.tables WHERE database = %(db)s", parameters={"db": table_name} ) # 서버 측 매개변수 사용 result = client.command( "SELECT count() FROM system.tables WHERE database = {db:String}", parameters={"db": "system"} ) ```

설정이 포함된 명령

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # 특정 설정을 사용해 명령 실행 result = client.command( "OPTIMIZE TABLE large_table FINAL", settings={"optimize_throw_if_noop": 1} ) ```

Client `query` 메서드

`Client.query`는 ClickHouse Native 형식의 테이블형 데이터셋을 가져와 `QueryResult`를 반환합니다. 결과 속성에 접근하는 시점에 전체 결과가 구체화됩니다. 메모리에 보관하지 않아야 하는 결과에는 스트리밍 메서드를 사용하세요. 클라이언트가 쿼리 끝의 `LIMIT 0`을 인식하면 JSON 포맷의 컬럼 메타데이터를 요청합니다. 응답에 행이 포함되어 있으면 `clickhouse_connect.driver.exceptions.InternalError`를 발생시키며 쿼리를 다시 실행하지 않습니다. 이는 `LIMIT 0`으로 끝나는 `UNION`, `EXCEPT`, 또는 `EXPLAIN` 쿼리에서 발생할 수 있습니다. 이러한 쿼리에는 `fmt="JSON"`과 같은 출력 형식과 함께 [`raw_query`](/ko/integrations/language-clients/python/advanced-usage#client-rawquery-method)를 사용하세요. 이 메서드는 `bytes`를 반환하므로 애플리케이션에서 디코딩해야 합니다. 이 동작은 동기 HTTP, 비동기 HTTP 및 chDB 클라이언트에 적용됩니다. | 매개변수 | 유형 | 기본값 | 설명 | | - | - | - | - | | `query` | str | 필수 | 테이블형 결과를 반환하는 ClickHouse 쿼리이며, 대부분 `SELECT` 또는 `DESCRIBE`입니다. `context`에서 제공되는 경우 생략할 수 있습니다. | | `parameters` | dict or sequence | `None` | [매개변수 인수](#parameters-argument)를 참조하세요. | | `settings` | dict | `None` | [설정 인수](#settings-argument-1)를 참조하세요. | | `query_formats` | dict | `None` | ClickHouse 타입별 읽기 포맷입니다. [읽기 포맷](/ko/integrations/language-clients/python/advanced-querying#read-formats)을 참조하세요. | | `column_formats` | dict | `None` | Nested type 포맷 매핑을 포함한 결과 컬럼별 읽기 포맷입니다. | | `encoding` | str | `None` | String 컬럼 인코딩입니다. 기본값은 UTF-8입니다. | | `use_none` | bool | `True` | SQL NULL에 대해 `None`을 반환합니다. `false`이면 해당 유형의 기본 NULL 값을 반환합니다. NumPy/Pandas 메서드는 성능 중심의 기본값을 선택합니다. | | `column_oriented` | bool | `False` | 결과를 행이 아닌 컬럼 기준으로 반환합니다. | | `use_numpy` | bool | `False` | 호환되는 결과 컬럼을 `QueryResult` 내부의 NumPy 배열로 읽어옵니다. 원하는 결과가 하나의 NumPy 매트릭스라면 `query_np`를 사용하는 것이 좋습니다. | | `max_str_len` | int | `0` | `use_numpy`를 사용할 때 이 길이까지의 String 컬럼에 고정 폭 유니코드 dtype을 사용합니다. 0이면 object 배열을 사용합니다. | | `context` | `QueryContext` | `None` | 재사용 가능한 쿼리 Context입니다. 메서드에 명시적으로 전달한 인수는 context 값을 재정의합니다. | | `query_tz` | str or `tzinfo` | `None` | 모든 `DateTime` 및 `DateTime64` 결과 컬럼에 적용되는 시간대입니다. | | `column_tzs` | dict | `None` | 컬럼별 시간대 매핑입니다. | | `external_data` | `ExternalData` | `None` | 외부 파일 또는 바이너리 데이터입니다. [External data](/ko/integrations/language-clients/python/advanced-querying#external-data)를 참조하세요. | | `transport_settings` | dict | `None` | 이 요청에 추가되는 HTTP 헤더입니다. | | `tz_mode` | str | 클라이언트 기본값 | `"naive_utc"`, `"aware"`, 또는 `"schema"` 시간대 처리에 대한 쿼리별 재정의입니다. |

쿼리 예시

기본 쿼리

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Simple SELECT query result = client.query( "SELECT number, toString(number) AS label FROM numbers(3)" ) # Access results as rows for row in result.result_rows: print(row) # Output: # (0, '0') # (1, '1') # (2, '2') # Access column names and types print(result.column_names) # Output: ('number', 'label') print([col_type.name for col_type in result.column_types]) # Output: ['UInt64', 'String'] ```

쿼리 결과 조회하기

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3") # Row-oriented access (default) print(result.result_rows) # Output: [(0, '0'), (1, '1'), (2, '2')] # Column-oriented access print(result.result_columns) # Output: [[0, 1, 2], ['0', '1', '2']] # Named results (list of dictionaries) for row_dict in result.named_results(): print(row_dict) # Output: # {'number': 0, 'str': '0'} # {'number': 1, 'str': '1'} # {'number': 2, 'str': '2'} # First row as dictionary print(result.first_item) # Output: {'number': 0, 'str': '0'} # First row as tuple print(result.first_row) # Output: (0, '0') ```

클라이언트 측 매개변수를 사용한 쿼리

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # 딕셔너리 매개변수 사용 (printf 스타일) query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s" parameters = {"db": "system", "pattern": "%query%"} result = client.query(query, parameters=parameters) # 튜플 매개변수 사용 query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s" parameters = ("system", 5) result = client.query(query, parameters=parameters) ```

서버 측 매개변수를 사용하는 쿼리

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # 서버 측 바인딩 (보안이 강화되고 SELECT 쿼리 성능이 향상됨) query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}" parameters = {"db": "system", "tbl": "query_log"} result = client.query(query, parameters=parameters) ```

설정을 지정한 쿼리

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # 쿼리와 함께 ClickHouse 설정을 지정합니다 result = client.query( "SELECT sum(number) FROM numbers(1000000)", settings={ "max_block_size": 100000, "max_execution_time": 30 } ) ```

`QueryResult` 객체

기본 `query` 메서드는 다음 공개 속성을 포함하는 `QueryResult` 객체를 반환합니다. * `result_rows` -- 행 기준으로 구성된 결과 매트릭스입니다. * `result_columns` -- 컬럼 기준으로 구성된 결과 매트릭스입니다. * `result_set` -- 쿼리 방향에 따라 `result_rows` 또는 `result_columns`입니다. * `column_names` -- 결과 컬럼명의 `Tuple`입니다. * `column_types` -- `ClickHouseType` 객체의 `Tuple`입니다. * `row_count` -- 구체화된 결과 행 수입니다. * `query_id` -- 요청에 대해 보고되었거나 생성된 쿼리 ID입니다. 빈 문자열은 사용 가능한 값이 없었음을 의미합니다. * `summary` -- `X-ClickHouse-Summary` 응답 헤더에서 디코딩된 딕셔너리입니다. * `first_item` -- 딕셔너리 형식의 첫 번째 행이며, 결과가 비어 있으면 `None`입니다. * `first_row` -- 시퀀스 형식의 첫 번째 행이며, 결과가 비어 있으면 `None`입니다. * `column_block_stream`, `row_block_stream`, `rows_stream` -- 내부 스트림 컨텍스트입니다. 대신 해당 클라이언트의 스트리밍 메서드를 사용하십시오. 지원되는 `StreamContext` API는 [스트리밍 쿼리](/ko/integrations/language-clients/python/advanced-querying#streaming-queries)에서 확인하십시오.

NumPy, Pandas 또는 Arrow로 쿼리 결과 처리하기

ClickHouse Connect는 NumPy, Pandas, Arrow 데이터 포맷용 전용 쿼리 메서드를 제공합니다. 예시, 스트리밍 지원, 고급 타입 처리 등 이러한 메서드의 사용법에 관한 자세한 내용은 [고급 쿼리(NumPy, Pandas 및 Arrow 쿼리)](/ko/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries)를 참조하십시오.

클라이언트 스트리밍 쿼리 메서드

대규모 결과 집합(result set)을 스트리밍하려면 ClickHouse Connect에서 여러 스트리밍 메서드를 제공합니다. 자세한 내용과 예시는 [고급 쿼리(Streaming Queries)](/ko/integrations/language-clients/python/advanced-querying#streaming-queries)를 참조하십시오.

클라이언트 `insert` 메서드

여러 레코드를 ClickHouse에 삽입하는 일반적인 경우에는 `Client.insert` 메서드를 사용합니다. 이 메서드는 다음 매개변수를 받습니다. | Parameter | Type | Default | Description | | - | - | - | - | | `table` | str | Required | 대상 테이블입니다. 데이터베이스를 포함한 이름도 사용할 수 있습니다. `context`에서 제공하는 경우 생략할 수 있습니다. | | `data` | Sequence of Sequences | Required | 행 지향 또는 컬럼 지향 데이터 매트릭스입니다. 나중에 `InsertContext`를 통해 제공할 수도 있습니다. | | `column_names` | str or Sequence\[str] | `"*"` | 순서가 지정된 컬럼입니다. `"*"`를 사용하면 삽입 가능한 모든 컬럼을 찾기 위해 메타데이터 쿼리를 실행합니다. | | `database` | str or None | Client database | `table`에 데이터베이스가 지정되지 않은 경우의 대상 데이터베이스입니다. | | `column_types` | Sequence\[`ClickHouseType`] | `None` | 명시적인 컬럼 타입입니다. 제공하면 메타데이터 쿼리를 실행하지 않아도 됩니다. | | `column_type_names` | Sequence\[str] | `None` | 명시적인 ClickHouse 타입 이름입니다. `column_types` 대신 사용할 수 있습니다. | | `column_oriented` | bool | `False` | `data`를 행이 아닌 컬럼으로 해석합니다. | | `settings` | dict | `None` | [설정 인수](#settings-argument-1)를 참조하십시오. | | `context` | `InsertContext` | `None` | 재사용 가능한 삽입 컨텍스트입니다. [InsertContexts](/ko/integrations/language-clients/python/advanced-inserting#insertcontexts)를 참조하십시오. | | `transport_settings` | dict | `None` | 이 요청에 추가되는 HTTP 헤더입니다. | 이 메서드는 `QuerySummary`를 반환합니다. 이 객체의 `summary` 딕셔너리에는 서버가 보고한 값이 포함됩니다. `written_rows`는 편의 속성이며, `written_bytes()`와 `query_id()`는 해당 값을 반환합니다. 삽입이 실패하면 예외가 발생합니다. Pandas DataFrame, PyArrow 테이블, Arrow 기반 DataFrame에서 작동하는 특수 삽입 메서드는 [고급 삽입(특수 삽입 메서드)](/ko/integrations/language-clients/python/advanced-inserting#specialized-insert-methods)를 참조하십시오. NumPy 배열은 유효한 Sequence of Sequences이므로 기본 `insert` 메서드의 `data` 인수로 사용할 수 있으며, 별도의 특수 메서드는 필요하지 않습니다.

예시

아래 예시에서는 스키마(schema)가 `(id UInt32, name String, age UInt8)`인 기존 `users` 테이블(table)이 이미 있다고 가정합니다.

기본적인 행 지향 삽입

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Row-oriented data: each inner list is a row data = [ [13, "user_1", 25], [79, "user_2", 30], ] client.insert("users", data, column_names=["id", "name", "age"]) ```

컬럼 지향 방식 삽입

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Column-oriented data: each inner list is a column data = [ [13, 79], # id column ["user_1", "user_2"], # name column [25, 30], # age column ] client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True) ```

명시적으로 컬럼 타입을 지정해 삽입

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() # Useful when you want to avoid a DESCRIBE query to the server data = [ [13, "user_1", 25], [79, "user_2", 30], ] client.insert( "users", data, column_names=["id", "name", "age"], column_type_names=["UInt32", "String", "UInt8"], ) ```

특정 데이터베이스에 삽입하기

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client() data = [ [13, "user_1", 25], [79, "user_2", 30], ] # Insert into a table in a specific database client.insert( "users", data, column_names=["id", "name", "age"], database="production", ) ```

파일 삽입

파일의 데이터를 ClickHouse 테이블에 직접 삽입하는 방법은 [고급 삽입(파일 삽입)](/ko/integrations/language-clients/python/advanced-inserting#file-inserts)을 참조하십시오.

Raw API

유형 변환 없이 ClickHouse HTTP 인터페이스에 직접 액세스해야 하는 고급 사용 사례는 [고급 사용법(Raw API)](/ko/integrations/language-clients/python/advanced-usage#raw-api)을 참조하십시오.

Python DB-API 2.0

`clickhouse_connect.dbapi` 모듈은 PEP 249의 연결 및 cursor 인터페이스를 구현합니다. 이 모듈은 API 수준 2.0, `threadsafety=2`, `paramstyle="pyformat"`를 선언합니다. 또한 PEP 249 유형 생성자인 `Date`, `Time`, `Timestamp`, `Binary`와 `DateFromTicks`, `TimeFromTicks`, `TimestampFromTicks` 함수를 제공합니다. 이 모듈은 PEP 249 예외 계층 구조인 `Warning`, `Error`, `InterfaceError`, `DatabaseError`, `DataError`, `OperationalError`, `IntegrityError`, `InternalError`, `ProgrammingError`, `NotSupportedError`를 내보냅니다. 이들은 `clickhouse_connect.driver.exceptions`에서 제공하는 것과 동일한 클래스 객체이므로, 어느 import 경로를 사용하더라도 드라이버 오류를 잡을 수 있습니다. 드라이버 전용 예외인 `StreamFailureError`는 여전히 `clickhouse_connect.driver.exceptions`에서 사용할 수 있으며, `OperationalError`의 하위 클래스입니다. ```python theme={null} from clickhouse_connect import dbapi connection = dbapi.connect( host="localhost", username="default", password="password", database="default", ) cursor = connection.cursor() try: cursor.execute( "SELECT name FROM system.tables " "WHERE database = %(database)s ORDER BY name LIMIT 5", {"database": "system"}, ) print(cursor.description) print(cursor.fetchall()) finally: cursor.close() connection.close() ``` `Cursor.execute` 및 `Cursor.executemany`는 추가 `settings` 및 `query_formats` 키워드 인수를 받습니다. `settings`는 ClickHouse 설정을 전달합니다. `query_formats`는 SQL 문이 행을 반환할 때 `Client.query`와 동일한 매핑을 사용하여 ClickHouse 타입별 읽기 포맷을 적용합니다. 두 메서드 모두 키워드 전용 `pyformat_encoded` 인수도 받습니다. 기본값 `True`는 DB-API `pyformat` 규약을 따릅니다. SQLAlchemy 방언은 SQL 문 컴파일러가 원시 백분율 기호를 생성한 경우 이를 `False`로 설정하므로, 일반적으로 애플리케이션에서 설정할 필요가 없습니다. 매개변수화된 `Cursor.executemany` 작업은 SQL 바인딩 및 표현식 의미 체계를 유지하면서 매개변수 세트마다 한 번씩 실행됩니다. HTTP를 사용하는 경우 매개변수 세트마다 요청이 하나씩 전송됩니다. 뒤쪽의 매개변수 세트가 실패하더라도 앞서 수행된 쓰기는 커밋된 상태로 남습니다. 이러한 `executemany` 삽입에서 `Cursor.rowcount`는 ClickHouse가 보고한 `written_rows` 값의 합계이며, 해당 값을 사용할 수 없으면 `-1`입니다. `Cursor.execute`로 전송한 INSERT SQL 문은 `0`을 보고합니다. 플레이스홀더가 없는 `INSERT INTO table (columns) VALUES` 호환 형식은 네이티브 삽입을 사용합니다. `VALUES`로 끝나는 플레이스홀더 없는 INSERT가 이 호환 형식으로 인식되지 않으면 `ProgrammingError`가 발생합니다. 명시적인 네이티브 대량 삽입이 필요한 애플리케이션에서는 `Client.insert`를 사용하십시오. `fetchone`, `fetchmany`, `fetchall`은 현재 구체화된 결과에서 데이터를 가져옵니다. `Cursor.description`은 각 결과 컬럼 타입을 바탕으로 `null_ok`를 결정합니다. 널을 허용하지 않는 타입은 `False`를 보고하고, `Nullable` 래퍼, `Variant`, `Dynamic`을 포함한 널 허용 타입은 `True`를 보고합니다. `None`은 널 허용 여부를 알 수 없음을 의미합니다. 선행 주석을 무시하고 `SELECT` 또는 `WITH`로 시작하는 쿼리가 행이나 컬럼 메타데이터를 반환하지 않으면, cursor는 `description`을 채우기 위해 `LIMIT 0` 메타데이터 쿼리를 실행합니다. 해당 메타데이터 쿼리가 실패하면 `description`은 비어 있는 상태로 유지됩니다. ClickHouse는 이 HTTP 인터페이스를 통해 전통적인 트랜잭션을 제공하지 않습니다. `Connection.commit()` 및 `Connection.rollback()`은 아무 작업도 수행하지 않습니다. 연결을 공유하는 경우에도 [session ID 동시성 규칙](/ko/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids)이 계속 적용됩니다.

유틸리티 클래스와 함수

다음 모듈은 클라이언트 애플리케이션에서 사용하는 추가 공개 도우미를 제공합니다. 설치된 패키지 버전은 문자열 `clickhouse_connect.__version__`으로 노출됩니다.

예외

`clickhouse_connect.dbapi`에서 다시 내보내는 DB-API 2.0 예외 계층을 포함한 사용자 정의 예외는 `clickhouse_connect.driver.exceptions`에 정의되어 있습니다. `DatabaseError`와 `OperationalError`는 ClickHouse 오류 코드가 담긴 숫자 `code` 속성과 `UNKNOWN_TABLE` 같은 기호 이름이 담긴 `name` 속성을 제공하므로, 애플리케이션은 메시지를 파싱하지 않고 `exc.code`를 기준으로 분기할 수 있습니다. `show_clickhouse_errors`가 비활성화되어 있어도 `code`는 설정되지만, `name`을 사용하려면 오류 세부 정보(`True` 또는 `"scrub"`)가 필요합니다. 전송 오류처럼 사용할 수 없는 경우에는 둘 다 `None`입니다. 최종 사용자에게 호스트 또는 서버 버전 정보 없이 SQL 오류를 표시해야 하는 경우 `show_clickhouse_errors="scrub"`를 사용하십시오. 이 설정은 스트림 도중 발생하는 `StreamFailureError` 메시지와 일반 전송 메시지도 제어합니다. 이 설정은 `str(exc)`에만 적용됩니다. 전송 오류는 여전히 `__cause__`로 연결되며, 트레이스백에는 원래 호스트, URL 또는 라이브러리 오류 텍스트가 포함될 수 있습니다.

ClickHouse SQL 유틸리티

`clickhouse_connect.driver.binding` 모듈의 함수와 DT64Param 클래스는 ClickHouse SQL 쿼리를 올바르게 구성하고 이스케이프 처리하는 데 사용할 수 있습니다. 마찬가지로 `clickhouse_connect.driver.parser` 모듈의 함수는 ClickHouse 데이터 타입 이름을 파싱하는 데 사용할 수 있습니다.

멀티스레드, 멀티프로세스 및 비동기/이벤트 기반 사용 사례

멀티스레드, 멀티프로세스 및 비동기/이벤트 기반 애플리케이션에서 ClickHouse Connect를 사용하는 방법에 대한 자세한 내용은 [고급 사용법(멀티스레드, 멀티프로세스 및 비동기/이벤트 기반 사용 사례)](/ko/integrations/language-clients/python/advanced-usage#multithreaded-multiprocess-and-asyncevent-driven-use-cases)를 참조하십시오.

AsyncClient

asyncio 환경에서 네이티브로 사용하는 방법은 [고급 사용법(AsyncClient)](/ko/integrations/language-clients/python/advanced-usage#asyncclient)를 참조하십시오.

ClickHouse 세션 ID 관리

멀티스레드 또는 동시 처리 애플리케이션에서 ClickHouse 세션 ID를 관리하는 방법에 대한 자세한 내용은 [고급 사용법(ClickHouse 세션 ID 관리)](/ko/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids)을 참조하십시오.

HTTP 연결 풀 사용자 지정

대규모 멀티스레드 애플리케이션에서 HTTP 연결 풀을 사용자 지정하는 방법에 대한 자세한 내용은 [고급 사용법(HTTP 연결 풀 사용자 지정)](/ko/integrations/language-clients/python/advanced-usage#customizing-the-http-connection-pool)을 참조하십시오.