추가 옵션 | ClickHouse Docs

ClickHouse Connect는 고급 활용 사례를 위한 다양한 추가 옵션을 제공합니다.

전역 설정

ClickHouse Connect의 동작을 전역적으로 제어하는 몇 가지 설정이 있습니다. 이러한 설정은 최상위 common package에서 액세스할 수 있습니다:

from clickhouse_connect import common

common.set_setting("autogenerate_session_id", False)
print(common.get_setting("invalid_setting_action"))
# Output: error

Note

클라이언트를 생성하기 전에 클라이언트 생성 설정을 구성하십시오. 생성된 session/query ID 및 제품 식별과 같은 설정은 클라이언트별 상태에 복사되므로, 이후 전역적으로 변경해도 기존 클라이언트에는 반영되지 않습니다. 바인딩 및 삽입 설정은 이와 다릅니다. naive_datetime_binding 및 dict_parameter_format은 매개변수를 바인딩할 때 읽습니다. naive_datetime_insert는 Python datetime 객체 또는 DateTime64 ISO 문자열이 포함된 네이티브 삽입 컬럼을 직렬화할 때 읽습니다. 이러한 설정을 변경하면 기존 클라이언트에도 영향을 미칩니다. 재사용 가능한 삽입 컨텍스트는 삽입할 때마다 현재 naive_datetime_insert 값을 사용합니다.

현재 다음 전역 설정이 정의되어 있습니다.

설정 이름	기본값	옵션	설명
`autogenerate_session_id`	`True`	`True`, `False`	session ID가 제공되지 않으면 각 동기 클라이언트에 UUID session ID를 생성합니다. 비동기 팩토리는 기본적으로 이를 `False`로 재정의합니다.
`autogenerate_query_id`	`True`	`True`, `False`	제공되지 않으면 각 요청에 UUID 쿼리 ID를 생성합니다.
`dict_parameter_format`	`"json"`	`"json"`, `"map"`	매개변수 바인딩에 사용하는 Python 딕셔너리를 JSON 또는 ClickHouse 맵 리터럴로 포맷합니다.
`invalid_setting_action`	`"error"`	`"drop"`, `"send"`, `"error"`	서버에서 readonly로 보고된 설정에 적용할 동작입니다. `drop`은 해당 설정을 무시하고, `send`는 전달하며, `error`는 `ProgrammingError`를 발생시킵니다. 역할에서 `CHANGEABLE_IN_READONLY`로 설정된 항목처럼 현재 사용자의 `system.settings`에 없는 설정은 동작이 `drop`이 아닌 한 서버가 수락하거나 거부하도록 전달됩니다.
`naive_datetime_binding`	`"wall"`	`"wall"`, `"legacy"`	naive `datetime` 쿼리 매개변수의 바인딩 방식을 제어합니다. `wall`은 naive datetime을 있는 그대로 포맷합니다. `legacy`는 이전의 호스트 로컬 변환 동작을 복원합니다. 특정 시점을 보존하려면 `tzinfo`를 지정하십시오.
`naive_datetime_insert`	`"local"`	`"local"`, `"server"`	naive `datetime` 값과 `DateTime64`에서 허용하는 naive ISO 문자열의 Python 객체 삽입을 제어합니다. `local`은 호환성을 위해 프로세스 시간대를 사용합니다. `server`는 선언된 컬럼 시간대를 사용하고, 없으면 서버 시간대를 사용합니다. `datetime64`-dtype NumPy 및 Pandas 컬럼은 변경되지 않습니다.
`max_connection_age`	`600`	임의의 초 단위 숫자	재사용되는 HTTP keep-alive 연결의 최대 수명입니다. 연결을 교체하면 로드 밸런서 뒤의 노드에 연결을 분산하는 데 도움이 됩니다.
`product_name`	`""`	임의의 문자열	클라이언트 정보에 추가되는 제품 식별자입니다. `"my-product/1.0"`과 같은 값을 사용하십시오.
`readonly`	`0`	`0`, `1`	1.x 호환성을 위해 유지되는 Deprecated 무작동 설정입니다. 클라이언트는 서버의 `readonly` 설정을 직접 읽습니다.
`send_os_user`	`True`	`True`, `False`	감지된 운영 체제 사용자를 클라이언트 정보에 포함합니다.
`send_integration_tags`	`True`	`True`, `False`	Pandas 또는 SQLAlchemy와 같이 클라이언트가 사용하는 통합 정보를 HTTP User-Agent에 포함합니다.
`use_protocol_version`	`True`	`True`, `False`	`DateTime` 컬럼 시간대 메타데이터와 같은 네이티브 포맷 기능에서 사용하는 클라이언트 protocol version을 협상합니다. `client_protocol_version`을 거부하는 프록시에서는 이를 비활성화하십시오.
`max_error_size`	`1024`	임의의 음이 아닌 정수	클라이언트 오류에 포함할 최대 문자 수입니다. 전체 메시지를 표시하려면 `0`을 사용하십시오.
`http_buffer_size`	`10485760`	바이트	스트리밍 HTTP 쿼리를 위한 인메모리 버퍼 크기이며, 기본값은 10 MiB입니다.

압축

ClickHouse Connect는 lz4, zstd, brotli, gzip, deflate 응답 압축을 지원합니다. 네이티브 삽입은 lz4, zstd, brotli, gzip을 지원합니다. 압축을 사용하면 네트워크 전송량을 줄이는 대신 CPU 시간을 더 사용합니다.

압축된 데이터를 받으려면 ClickHouse 서버의 enable_http_compression이 1로 설정되어 있어야 하거나, 사용자가 쿼리별로 이 설정을 변경할 권한을 가지고 있어야 합니다.

압축은 get_client 및 get_async_client의 compress 인수로 제어합니다. 기본값 True는 사용 가능한 모든 응답 인코딩을 알리고, 네이티브 삽입 블록을 lz4로 압축합니다. 압축을 비활성화하려면 compress=False로 설정하고, 특정 메서드를 요청하려면 "lz4", "zstd", "br", "gzip" 중 하나를 전달하십시오.

raw 클라이언트 메서드는 클라이언트 수준의 compress 설정을 사용하지 않습니다. raw_query와 raw_stream은 비압축 데이터를 반환하며, raw_insert는 payload에 이미 적용된 압축을 설명하는 자체 compression 인수를 받습니다.

lz4 및 zstd 지원은 ClickHouse Connect와 함께 설치됩니다. Python 3.14에서는 zstd가 표준 라이브러리 compression.zstd 모듈을 사용합니다. Python 3.10부터 3.13까지는 backports.zstd를 사용합니다. zstd 지원 없이 빌드된 사용자 지정 CPython 3.14+ 인터프리터도 가져오기는 가능하지만, 이 경우 zstd는 사용 가능한 메서드에서 제외되며 zstd를 명시적으로 요청할 때만 오류가 발생합니다. Brotli는 선택 사항이므로 compress="br"를 사용하기 전에 별도로 설치해야 합니다.

ClickHouse 워크로드에서는 일반적으로 gzip이 lz4 또는 zstd보다 느립니다.

HTTP 프록시 지원

ClickHouse Connect는 표준 HTTP_PROXY 및 HTTPS_PROXY 환경 변수를 인식합니다. 이 변수들은 해당 프로세스의 모든 클라이언트에 적용됩니다. 클라이언트별로 프록시를 구성하려면 http_proxy 또는 https_proxy를 get_client 또는 get_async_client에 전달하세요.

동기 클라이언트는 urllib3를 사용합니다. SOCKS 프록시를 사용하려면 PySocks를 설치한 다음, urllib3.contrib.socks.SOCKSProxyManager를 pool_mgr 인수로 get_client에 전달하세요. pool_mgr는 async 클라이언트에서 지원되지 않습니다.

Variant, Dynamic, 및 JSON 데이터 타입

ClickHouse Connect는 현재 ClickHouse의 Variant, Dynamic, JSON 데이터 타입을 지원합니다. 이전 Object('json') 타입은 clickhouse-connect 0.14에서 제거되었으며 현재는 지원되지 않습니다.

사용 시 참고 사항

Variant 값은 해당 Python 타입으로 읽힙니다. 네이티브 삽입에서는 Python 값의 타입에 따라 멤버를 선택합니다.
여러 Variant 멤버가 동일한 Python 타입에 매핑되는 경우, 멤버를 명시적으로 선택하려면 값을 clickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName")로 감싸십시오.
typed Variant 읽기 포맷은 TypedVariant(value, type_name) 객체를 반환하며, 원래 멤버 타입을 유지합니다. query_formats={"Variant": "typed"}로 활성화하십시오.
Dynamic 값은 해당 Python 타입으로 읽힙니다. 현재 삽입은 String 표현을 통해 전송됩니다.
JSON 값은 Python 딕셔너리 또는 JSON 객체 문자열로 삽입할 수 있습니다. 기본 읽기 포맷은 딕셔너리를 반환하며, JSON 문자열을 반환하려면 "string" 읽기 포맷을 사용하십시오.
Variant, Dynamic 또는 JSON 서브컬럼(subcolumn)을 선택하는 쿼리는 해당 서브컬럼의 구체적인 타입을 반환합니다.

JSON 또는 Dynamic 컬럼의 shared-data 영역에 저장된 일부 값은 클라이언트가 아직 디코딩할 수 없는 타입을 사용합니다. 이러한 값은 원시 바이트(raw bytes)로 반환됩니다. 이러한 복합 타입은 pure Python 변환 경로도 사용하므로, 일반적인 스칼라 타입보다 더 느릴 수 있습니다.