追加オプション | ClickHouse Docs

ClickHouse Connect には、より高度な用途に対応する追加オプションがいくつか用意されています。

グローバル設定

ClickHouse Connect の動作全体を制御する設定がいくつかあります。これらの設定には、トップレベルの common パッケージからアクセスできます。

from clickhouse_connect import common

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

Note

クライアントを作成する前に、クライアント作成設定を構成してください。生成されるセッション ID／クエリ ID や製品識別情報などの設定はクライアント固有の状態にコピーされるため、後からグローバル設定を変更しても既存のクライアントには反映されません。バインディングと insert に関する設定は異なります。naive_datetime_binding と dict_parameter_format は、パラメータのバインド時に読み取られます。naive_datetime_insert は、Python の datetime オブジェクトまたは DateTime64 の ISO 文字列を含むネイティブ insert カラムをシリアル化する際に読み取られます。これらの設定を変更すると、既存のクライアントにも影響します。再利用可能な insert コンテキストでは、insert ごとに現在の naive_datetime_insert 値が使用されます。

現在定義されているグローバル設定は次のとおりです。

設定名	デフォルト	オプション	説明
`autogenerate_session_id`	`True`	`True`, `False`	セッション ID が指定されていない場合、同期クライアントごとに UUID セッション ID を生成します。非同期ファクトリーでは、デフォルトでこれを `False` に上書きします。
`autogenerate_query_id`	`True`	`True`, `False`	指定されていない場合、リクエストごとに UUID クエリ ID を生成します。
`dict_parameter_format`	`"json"`	`"json"`, `"map"`	パラメータバインディングで使用する Python 辞書を、JSON または ClickHouse の map リテラルとしてフォーマットします。
`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 オブジェクトとして insert する際の動作を制御します。`local` は互換性のためにプロセスのタイムゾーンを使用します。`server` は宣言されたカラムのタイムゾーンを使用し、次にサーバーのタイムゾーンを使用します。`datetime64`-dtype の NumPy および Pandas カラムは変更されません。
`max_connection_age`	`600`	任意の秒数	再利用される HTTP keep-alive 接続の最大存続時間です。接続をローテーションすることで、load balancer 配下のノード間に接続を分散できます。
`product_name`	`""`	任意の文字列	クライアント情報に追加する製品識別子です。`"my-product/1.0"` のような値を使用してください。
`readonly`	`0`	`0`, `1`	1.x との互換性のために残されている非推奨の無効設定です。クライアントはサーバーの `readonly` 設定を直接読み取ります。
`send_os_user`	`True`	`True`, `False`	検出された OS ユーザーをクライアント情報に含めます。
`send_integration_tags`	`True`	`True`, `False`	Pandas や SQLAlchemy など、クライアントで使用されるインテグレーションを HTTP User-Agent に含めます。
`use_protocol_version`	`True`	`True`, `False`	`DateTime` カラムのタイムゾーンメタデータなど、Native フォーマット機能で使用するクライアントプロトコルバージョンをネゴシエートします。`client_protocol_version` を拒否するプロキシでは、これを無効にしてください。
`max_error_size`	`1024`	任意の非負整数	クライアントエラーに含める最大文字数です。完全なメッセージを取得するには `0` を使用してください。
`http_buffer_size`	`10485760`	バイト	ストリーミング HTTP クエリ用のインメモリバッファサイズです。デフォルトは 10 MiB です。

圧縮

ClickHouse Connect は、レスポンス圧縮として lz4、zstd、brotli、gzip、deflate をサポートしています。ネイティブ insert は lz4、zstd、brotli、gzip をサポートしています。圧縮では、ネットワーク転送量を削減する代わりに CPU時間を消費します。

圧縮されたデータを受信するには、ClickHouse server の 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プロキシサポート

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 型として読み取られます。ネイティブ 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 型より低速になる場合があります。