Rust 네이티브 코덱

​

설치

pip install "clickhouse-connect[rust]"         # Python rows and Native inserts
pip install "clickhouse-connect[rust,numpy]"   # NumPy results
pip install "clickhouse-connect[rust,pandas]"  # Pandas results and inserts

pip install "clickhouse-connect[rust,pandas,arrow]"

​

코덱 활성화

import clickhouse_connect

client = clickhouse_connect.get_client(host="localhost", native_codec="rust")

​

Rust 코덱을 사용해야 하는 경우

​

폴백 규칙

​

버전 관리

pip install --upgrade clickhouse-connect-core

​

알려진 동작 차이

• Variant 컬럼의 query_np 및 query_df 결과에는 numpy 스칼라 값이 아닌 일반 Python 객체가 담깁니다. 값은 동일하지만 셀 타입이 다릅니다.
• Time64를 포함하는 Dynamic 값은 Rust의 query_np 및 query_df 결과에서 datetime.timedelta로 구체화됩니다. scale이 0, 3, 6, 9일 때는 값이 Python 코덱의 numpy.timedelta64 셀과 동일하지만 셀 타입이 다릅니다. 그 외의 scale에서는 Rust 코덱이 datetime.timedelta를 반환하는 반면, Python 코덱은 NumPy에 대응하는 단위가 없어 ProgrammingError를 발생시킵니다. Rust로 디코딩한 뒤에는 Dynamic 멤버 메타데이터가 드라이버에 노출되지 않으므로, NumPy 셀 타입이나 지원되지 않는 scale에 대한 유효성 검사가 필요하다면 native_codec="python"을 사용하십시오.
• query_df에서 Python 코덱은 JSON shared data에 저장된 Compound 값을 문자열로 변환할 수 있습니다. Rust 코덱은 디코딩된 객체를 반환하며, 이는 두 코덱의 query_np 결과와 일치합니다.
• Array(Variant(...))처럼 셀 단위로 구체화되는 컨테이너 내부의 LowCardinality 대안은 값이 동일한 셀을 생성하지만, Python 코덱에서 나타나는 딕셔너리 슬롯 단위의 객체 아이덴티티는 공유하지 않습니다.
• 원소가 하나 이상인 Nullable(Tuple(...)) 컬럼은 Rust 코덱에서 올바르게 디코딩됩니다. Python 코덱은 이 layout을 잘못 읽으며, Rust 결과가 기준 동작입니다. 두 코덱 모두 Nullable(Tuple())을 지원합니다.
• rust_strict는 쿼리별 사용자 정의 query_formats처럼 Rust 경로가 구현하지 않은 쿼리 옵션을, 동작을 조용히 바꾸는 대신 거부합니다.
• Rust의 삽입 변환 및 유효성 검사 오류는 Python 코덱이 ValueError를 발생시키는 상황에서 DataError를 발생시킬 수 있으며, 메시지 문구도 다를 수 있습니다. 유효하지 않은 Time 및 Time64 값, IPv6 주소, QBit 차원, FixedString length, Float64 문자열, Tuple() 컬럼에 원소를 삽입하려는 시도 등이 이에 해당합니다.
• Rust 인코더는 FixedString(N)에 대한 b""와 정수 컬럼에 대한 "2" 같은 숫자 문자열을 거부합니다. 반면 Python 코덱은 비어 있는 FixedString 값을 0으로 채우고 숫자 문자열을 변환합니다.
• Python 코덱이 raw bytes 상태로 남겨두는 일부 Dynamic shared-variant 값을 Rust 코덱은 해당 Python 타입으로 디코딩합니다. 예를 들어 저장된 Decimal은 Rust에서는 decimal.Decimal로, Python에서는 이진 값으로 반환될 수 있습니다.
• Dynamic 공유 스토리지에 저장된 Date 값에 대해 query_np 및 query_df는 Rust 코덱에서는 datetime.date 셀을, Python 코덱에서는 numpy.datetime64 셀을 반환합니다. query에서는 두 코덱 모두 datetime.date를 반환합니다.