Additional options | ClickHouse Docs

ClickHouse Connect provides a number of additional options for advanced use cases.

Global settings

There are a handful of settings that control ClickHouse Connect behavior globally. They’re accessed from the top level common package:

from clickhouse_connect import common

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

The following global settings are currently defined:

Setting name	Default	Options	Description
`autogenerate_session_id`	`True`	`True`, `False`	Generate a UUID session ID for each synchronous client unless a session ID is supplied. The async factory overrides this to `False` by default.
`autogenerate_query_id`	`True`	`True`, `False`	Generate a UUID query ID for each request unless one is supplied.
`dict_parameter_format`	`"json"`	`"json"`, `"map"`	Format Python dictionaries used in parameter binding as JSON or ClickHouse map literals.
`invalid_setting_action`	`"error"`	`"drop"`, `"send"`, `"error"`	Action for a setting the server reports as readonly. `drop` ignores it, `send` forwards it, `error` raises `ProgrammingError`. Settings absent from `system.settings` for the current user, such as one made `CHANGEABLE_IN_READONLY` on a role, are forwarded so the server can accept or reject them, unless the action is `drop`.
`naive_datetime_binding`	`"wall"`	`"wall"`, `"legacy"`	Controls binding for naive `datetime` query parameters. `wall` formats naive datetimes verbatim. `legacy` restores the older host-local conversion behavior. Attach `tzinfo` to preserve an instant.
`naive_datetime_insert`	`"local"`	`"local"`, `"server"`	Controls Python object inserts of naive `datetime` values and naive ISO strings accepted by `DateTime64`. `local` uses the process timezone for compatibility. `server` uses the declared column timezone, then the server timezone. `datetime64`-dtype NumPy and Pandas columns are unchanged.
`max_connection_age`	`600`	Any number of seconds	Maximum age for a reused HTTP keep-alive connection. Rotation helps distribute connections across nodes behind a load balancer.
`native_codec`	`"python"`	`"python"`, `"rust"`, `"rust_strict"`	Default codec for client-managed Native format traffic, overridable per client. The `CLICKHOUSE_CONNECT_NATIVE_CODEC` environment variable seeds this setting at import. See Rust codec.
`product_name`	`""`	Any string	Product identifier added to client information. Use a value such as `"my-product/1.0"`.
`readonly`	`0`	`0`, `1`	Deprecated no-op retained for 1.x compatibility. The client reads the server’s `readonly` setting directly.
`send_os_user`	`True`	`True`, `False`	Include the detected operating system user in client information.
`send_integration_tags`	`True`	`True`, `False`	Include integrations used by the client, such as Pandas or SQLAlchemy, in the HTTP User-Agent.
`use_protocol_version`	`True`	`True`, `False`	Negotiate the client protocol version used by Native-format features such as `DateTime` column timezone metadata. Disable this for proxies that reject `client_protocol_version`.
`max_error_size`	`1024`	Any non-negative integer	Maximum number of characters included in a client error. Use `0` for the complete message.
`http_buffer_size`	`10485760`	Bytes	In-memory buffer size for streaming HTTP queries, 10 MiB by default.

Compression

ClickHouse Connect supports lz4, zstd, brotli, gzip, and deflate response compression. Native inserts support lz4, zstd, brotli, and gzip. Compression trades CPU time for reduced network transfer.

To receive compressed data, the ClickHouse server enable_http_compression must be set to 1, or the user must have permission to change the setting on a “per query” basis.

Compression is controlled by the compress argument to get_client and get_async_client. The default, True, advertises every available response encoding and compresses Native insert blocks with lz4. Set compress=False to disable compression or pass one of "lz4", "zstd", "br", or "gzip" to request a specific method.

The raw client methods don’t use the client-level compress setting. raw_query and raw_stream return uncompressed data, and raw_insert takes its own compression argument describing compression already applied to the payload.

lz4 and zstd support are installed with ClickHouse Connect. On Python 3.14, zstd uses the standard library compression.zstd module. Python 3.10 through 3.13 use backports.zstd. A custom CPython 3.14+ interpreter built without zstd support still imports; zstd is dropped from the available methods and an error is raised only when zstd is explicitly requested. Brotli is optional and must be installed separately before using compress="br".

gzip is generally slower than lz4 or zstd for ClickHouse workloads.

HTTP proxy support

ClickHouse Connect recognizes the standard HTTP_PROXY and HTTPS_PROXY environment variables. These variables apply to every client in the process. To configure a proxy per client, pass http_proxy or https_proxy to get_client or get_async_client.

The synchronous client uses urllib3. To use a SOCKS proxy, install PySocks and pass a urllib3.contrib.socks.SOCKSProxyManager as the pool_mgr argument to get_client. pool_mgr is not supported by the async client.

Variant, Dynamic, and JSON data types

ClickHouse Connect supports the current ClickHouse Variant, Dynamic, and JSON types. The legacy Object('json') type was removed in clickhouse-connect 0.14 and is not supported.

Usage notes

Variant values are read as the matching Python type. Native inserts select a member based on the Python value type.
When multiple Variant members map to the same Python type, wrap the value with clickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName") to select the member explicitly.
The typed Variant read format returns TypedVariant(value, type_name) objects and preserves the originating member type. Enable it with query_formats={"Variant": "typed"}.
Dynamic values are read as the matching Python type. Inserts are currently sent through the String representation.
JSON values can be inserted as Python dictionaries or JSON object strings. The default read format returns dictionaries; use the "string" read format to return JSON strings.
Queries that select a Variant, Dynamic, or JSON subcolumn return the subcolumn’s concrete type.

Parsed Variant, Dynamic, and JSON type names use ClickHouse’s canonical argument order. Variant members are sorted and deduplicated by canonical type name, including when a Variant is nested inside another type. Dynamic type names keep the max_types argument, so a Dynamic(max_types=5) column reports as Dynamic(max_types=5) rather than Dynamic. JSON typed paths and skip rules are sorted, duplicate plain skip paths are removed, regular expression duplicates are preserved, and explicit default limits are omitted. A parsed JSON type exposes decoded rules through skip_paths and skip_regexps. Its skips attribute contains the corresponding canonical ClickHouse expressions.

Some values stored in the shared-data area of JSON or Dynamic columns use types that the client cannot yet decode. Those values are returned as raw bytes. These complex types also use the pure Python conversion path, so they can be slower than established scalar types.