> ## 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.
> ClickHouse Connect의 추가 옵션
# 추가 옵션
ClickHouse Connect는 고급 활용 사례를 위한 다양한 추가 옵션을 제공합니다.
## 전역 설정
ClickHouse Connect의 동작을 전역적으로 제어하는 몇 가지 설정이 있습니다. 이러한 설정은 최상위 `common` package에서 액세스할 수 있습니다:
```python theme={null}
from clickhouse_connect import common
common.set_setting("autogenerate_session_id", False)
print(common.get_setting("invalid_setting_action"))
# Output: error
```
클라이언트를 생성하기 전에 클라이언트 생성 설정을 구성하십시오. 생성된 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 변환 경로도 사용하므로, 일반적인 스칼라 타입보다 더 느릴 수 있습니다.