전역 설정
common 패키지에서 사용합니다:
이러한 공통 설정
autogenerate_session_id, product_name, readonly는 clickhouse_connect.get_client 메서드로 클라이언트를 생성하기 전에 반드시 수정해야 합니다. 클라이언트를 생성한 후 이러한 설정을 변경해도 기존 클라이언트의 동작에는 영향을 주지 않습니다.| Setting Name | Default | Options | Description |
|---|---|---|---|
| autogenerate_session_id | True | True, False | 각 클라이언트 세션에 대해 새 UUID(1) 세션 ID를 자동 생성합니다(제공되지 않은 경우). 세션 ID가 제공되지 않으면(클라이언트 수준이든 쿼리 수준이든) ClickHouse가 각 쿼리마다 임의의 내부 ID를 생성합니다. |
| dict_parameter_format | ’json' | 'json’, ‘map’ | 매개변수화된 쿼리에서 Python 딕셔너리를 JSON 또는 ClickHouse 맵(Map) 구문으로 변환할지 제어합니다. json은 JSON 컬럼에 삽입할 때, map은 ClickHouse 맵 컬럼에 사용해야 합니다. |
| invalid_setting_action | ’error' | 'drop’, ‘send’, ‘error’ | 유효하지 않거나 readonly 설정이 제공되었을 때(클라이언트 세션 또는 쿼리 수준) 수행할 동작입니다. drop이면 해당 설정을 무시하고, send이면 해당 설정을 ClickHouse로 전송하며, error이면 클라이언트 측 ProgrammingError가 발생합니다. |
| max_connection_age | 600 | HTTP Keep Alive 연결을 열어 두거나 재사용할 최대 시간(초)입니다. 이렇게 하면 로드 밸런서/프록시 뒤에 있는 단일 ClickHouse 노드로 연결이 몰리는 현상을 방지할 수 있습니다. 기본값은 10분입니다. | |
| product_name | ClickHouse Connect를 사용하는 애플리케이션을 추적하기 위해 쿼리와 함께 ClickHouse로 전달되는 문자열입니다. 형식은 <product name;&gl/<product version>이어야 합니다. | ||
| readonly | 0 | 0, 1 | 19.17 이전 버전에서 암묵적으로 사용되는 “read_only” ClickHouse 설정입니다. 매우 오래된 ClickHouse 버전에서도 동작할 수 있도록 설정의 ClickHouse “read_only” 값에 맞춰 지정할 수 있습니다. |
| send_os_user | True | True, False | 감지된 운영 체제 사용자를 ClickHouse로 전송되는 클라이언트 정보에 포함합니다(HTTP User-Agent 문자열). |
| send_integration_tags | True | True, False | 사용 중인 통합 라이브러리와 해당 버전(예: Pandas/SQLAlchemy 등)을 ClickHouse로 전송되는 클라이언트 정보에 포함합니다(HTTP User-Agent 문자열). |
| use_protocol_version | True | True, False | 클라이언트 프로토콜 버전을 사용합니다. 이는 DateTime 시간대 컬럼에 필요하지만 현재 버전의 chproxy와는 호환되지 않습니다. |
| max_error_size | 1024 | 클라이언트 오류 메시지에 반환되는 최대 문자 수입니다. 전체 ClickHouse 오류 메시지를 받으려면 이 설정에 0을 사용하십시오. 기본값은 1024자입니다. | |
| http_buffer_size | 10MB | HTTP 스트리밍 쿼리에 사용되는 “인메모리” buffer의 크기(바이트)입니다. | |
| preserve_pandas_datetime_resolution | False | True, False | True이고 pandas 2.x를 사용하는 경우 datetime64/timedelta64 dtype 해상도(예: ‘s’, ‘ms’, ‘us’, ‘ns’)를 유지합니다. False이면(또는 pandas <2.x인 경우) 호환성을 위해 나노초(‘ns’) 해상도로 강제 변환합니다. |
압축
enable_http_compression이 1로 설정되어 있어야 하며, 또는 사용자가 쿼리별로 이 설정을 변경할 수 있는 권한을 가지고 있어야 합니다.
압축은 clickhouse_connect.get_client 팩토리 메서드를 호출할 때 compress 매개변수로 제어합니다. 기본적으로 compress는 True로 설정되어 있으며, 이 경우 기본 압축 설정이 적용됩니다. query, query_np, query_df 클라이언트 메서드로 실행되는 쿼리의 경우, ClickHouse Connect는 query 클라이언트 메서드로 실행되는 쿼리(그리고 간접적으로 query_np 및 query_df)에 lz4, zstd, br(brotli 라이브러리가 설치된 경우), gzip, deflate 인코딩이 포함된 Accept-Encoding 헤더를 추가합니다. (대부분의 요청에서는 ClickHouse 서버가 zstd로 압축된 페이로드를 반환합니다.) 삽입의 경우, 기본적으로 ClickHouse Connect는 삽입 블록을 lz4 압축으로 압축하고 Content-Encoding: lz4 HTTP 헤더를 전송합니다.
get_client의 compress 매개변수는 lz4, zstd, br, gzip 중 하나의 특정 압축 방식으로 설정할 수도 있습니다. 그러면 해당 방식이 삽입과 쿼리 결과 모두에 사용됩니다(ClickHouse 서버가 지원하는 경우). 필요한 zstd 및 lz4 압축 라이브러리는 이제 ClickHouse Connect와 함께 기본 설치됩니다. br/brotli를 지정하는 경우에는 brotli 라이브러리를 별도로 설치해야 합니다.
raw* 클라이언트 메서드는 클라이언트 구성에서 지정한 압축을 사용하지 않는다는 점에 유의하십시오.
또한 gzip 압축은 데이터 압축과 압축 해제 모두에서 다른 대안보다 현저히 느리므로 사용하지 않는 것이 좋습니다.
HTTP 프록시 지원
urllib3 라이브러리를 사용해 기본적인 HTTP 프록시 지원을 제공합니다. 표준 HTTP_PROXY 및 HTTPS_PROXY 환경 변수를 인식합니다. 이러한 환경 변수를 사용하면 clickhouse_connect.get_client 메서드로 생성된 모든 클라이언트에 적용된다는 점에 유의하십시오. 클라이언트별로 구성하려면 get_client 메서드의 http_proxy 또는 https_proxy 인수를 사용할 수도 있습니다. HTTP 프록시 지원 구현에 관한 자세한 내용은 urllib3 문서를 참조하십시오.
SOCKS 프록시를 사용하려면 urllib3의 SOCKSProxyManager를 get_client의 pool_mgr 인수로 전달하면 됩니다. 이 경우 PySocks 라이브러리를 직접 설치하거나 urllib3 의존성의 [socks] 옵션을 사용해 설치해야 합니다.
”기존” JSON 데이터 타입
Object(또는 Object('json')) 데이터 타입은 지원 중단 예정이므로 프로덕션 환경에서는 사용을 피해야 합니다. ClickHouse Connect는 이전 버전과의 호환성을 위해 이 데이터 타입에 대한 제한적인 지원을 계속 제공합니다. 다만 이 지원에는 “top level” 또는 “parent” JSON 값을 딕셔너리나 그에 준하는 형태로 반환하는 쿼리는 포함되지 않으며, 이러한 쿼리에서는 예외가 발생합니다.
”새” Variant/Dynamic/JSON 데이터 타입(실험적 기능)
clickhouse-connect는 새롭게 추가된(이 역시 실험적인) ClickHouse 타입인 Variant, Dynamic, JSON을 실험적으로 지원합니다.
사용 시 참고 사항
- JSON 데이터는 Python 딕셔너리 또는 JSON 객체
{}를 포함하는 JSON 문자열 형태로 삽입할 수 있습니다. 그 밖의 JSON 데이터 형식은 지원되지 않습니다. - 이러한 타입에서 서브컬럼/경로를 사용하는 쿼리는 해당 서브컬럼의 타입을 반환합니다.
- 다른 사용 시 참고 사항은 ClickHouse 문서를 참조하십시오.
알려진 제한 사항
- 이러한 각 타입은 사용하기 전에 ClickHouse 설정에서 활성화해야 합니다.
- “새” JSON 타입은 ClickHouse 24.8 릴리스부터 사용할 수 있습니다.
- 내부 포맷 변경으로 인해
clickhouse-connect는 ClickHouse 24.7 릴리스부터 Variant 타입에서만 호환됩니다. - 반환되는 JSON 객체에는
max_dynamic_paths개수만큼의 요소만 포함됩니다(기본값은 1024). 이 문제는 향후 릴리스에서 수정될 예정입니다. Dynamic컬럼에 대한 삽입은 항상 Python 값의 문자열 표현으로 처리됩니다. 이 문제는 https://github.com/ClickHouse/ClickHouse/issues/70395가 수정되면 향후 릴리스에서 해결될 예정입니다.- 새 타입 구현은 C 코드로 최적화되지 않았으므로, 더 단순하고 널리 사용되는 데이터 타입보다 성능이 다소 느릴 수 있습니다.