グローバル設定
common パッケージからアクセスできます。
クライアントを作成する前に、クライアント作成設定を構成してください。生成されるセッション ID／クエリ ID や製品識別情報などの設定はクライアント固有の状態にコピーされるため、後からグローバル設定を変更しても既存のクライアントには反映されません。バインディングと insert に関する設定は異なります。
naive_datetime_binding と dict_parameter_format は、パラメータのバインド時に読み取られます。naive_datetime_insert は、Python の datetime オブジェクトまたは DateTime64 の ISO 文字列を含むネイティブ insert カラムをシリアル化する際に読み取られます。これらの設定を変更すると、既存のクライアントにも影響します。再利用可能な insert コンテキストでは、insert ごとに現在の naive_datetime_insert 値が使用されます。圧縮
enable_http_compression を 1 に設定するか、ユーザーがクエリ単位でこの設定を変更する権限を持っている必要があります。
圧縮は、get_client と get_async_client の compress 引数で制御します。デフォルトの True では、利用可能なすべてのレスポンスエンコーディングを通知し、ネイティブ insert ブロックを lz4 で圧縮します。圧縮を無効にするには compress=False を設定し、特定のメソッドを要求するには "lz4"、"zstd"、"br"、"gzip" のいずれかを渡します。
raw client メソッドは、client レベルの compress 設定を使用しません。raw_query と raw_stream は非圧縮データを返し、raw_insert は payload にすでに適用されている圧縮を示す独自の compression 引数を受け取ります。
lz4 と zstd のサポートは ClickHouse Connect とともにインストールされます。Python 3.14 では、zstd は標準ライブラリの compression.zstd module を使用します。Python 3.10 から 3.13 では backports.zstd を使用します。zstd サポートなしでビルドされたカスタム CPython 3.14+ インタープリターでもインポート自体は可能ですが、利用可能なメソッドから zstd は除外され、zstd が明示的に要求された場合にのみエラーが発生します。Brotli はオプションであり、compress="br" を使用する前に別途インストールする必要があります。
一般に、ClickHouse のワークロードでは gzip は lz4 や zstd より低速です。
HTTPプロキシサポート
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 データ型
Variant、Dynamic、JSON 型をサポートしています。従来の Object('json') 型は clickhouse-connect 0.14 で削除され、サポートされていません。
使用上の注意
Variantの値は、対応する Python 型として読み取られます。ネイティブ insert では、Python の値の型に基づいてメンバーが選択されます。- 複数の
Variantメンバーが同じ Python 型に対応する場合は、clickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName")で値をラップして、メンバーを明示的に選択してください。 typedの Variant 読み取りフォーマットでは、TypedVariant(value, type_name)オブジェクトが返され、元のメンバー型が保持されます。有効にするには、query_formats={"Variant": "typed"}を使用します。Dynamicの値は、対応する Python 型として読み取られます。insert は現在、String 表現を通じて送信されます。JSONの値は、Python の辞書または JSON object 文字列として挿入できます。デフォルトの読み取りフォーマットでは辞書が返されます。JSON string を返すには、"string"読み取りフォーマットを使用してください。Variant、Dynamic、またはJSONのサブカラムを選択するクエリは、そのサブカラムの具体的な型を返します。
JSON または Dynamic カラムの shared-data 領域に格納された一部の値では、client がまだデコードできない型が使用されています。これらの値は raw bytes として返されます。これらの複雑な型でも pure Python の変換経路が使われるため、一般的な scalar 型より低速になる場合があります。