其他选项 | 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

当前定义了以下全局设置：

设置名称	默认值	选项	描述
`autogenerate_session_id`	`True`	`True`, `False`	除非提供了会话 ID，否则为每个同步客户端生成 UUID 会话 ID。异步工厂默认会将其覆盖为 `False`。
`autogenerate_query_id`	`True`	`True`, `False`	除非提供了查询 ID，否则为每个请求生成 UUID 查询 ID。
`dict_parameter_format`	`"json"`	`"json"`, `"map"`	将参数绑定中使用的 Python 字典格式化为 JSON 或 ClickHouse Map 字面量。
`invalid_setting_action`	`"error"`	`"drop"`, `"send"`, `"error"`	针对服务器报告为只读的设置采取的操作。`drop` 会忽略该设置，`send` 会将其转发，`error` 会引发 `ProgrammingError`。对于当前用户在 `system.settings` 中不存在的设置，例如在角色中设为 `CHANGEABLE_IN_READONLY` 的设置，除非操作为 `drop`，否则会将其转发，由服务器决定接受或拒绝。
`naive_datetime_binding`	`"wall"`	`"wall"`, `"legacy"`	控制朴素 `datetime` 查询参数的绑定方式。`wall` 会原样格式化朴素日期时间。`legacy` 会恢复旧版的主机本地时间转换行为。请附加 `tzinfo` 以保留时间点。
`naive_datetime_insert`	`"local"`	`"local"`, `"server"`	控制插入朴素 `datetime` 值以及 `DateTime64` 接受的朴素 ISO 字符串这两类 Python 对象的方式。`local` 为兼容性使用进程时区。`server` 使用声明的列时区，其次使用服务器时区。`datetime64`-dtype 的 NumPy 和 Pandas 列不受影响。
`max_connection_age`	`600`	任意秒数	可复用 HTTP keep-alive 连接的最长存活时间。轮换连接有助于将连接分散到负载均衡器后的各节点。
`product_name`	`""`	任意字符串	添加到客户端信息中的产品标识符。使用类似 `"my-product/1.0"` 的值。
`readonly`	`0`	`0`, `1`	为兼容 1.x 而保留的已弃用空操作设置。客户端会直接读取服务器的 `readonly` 设置。
`send_os_user`	`True`	`True`, `False`	在客户端信息中包含检测到的操作系统用户。
`send_integration_tags`	`True`	`True`, `False`	在 HTTP User-Agent 中包含客户端使用的集成信息，例如 Pandas 或 SQLAlchemy。
`use_protocol_version`	`True`	`True`, `False`	协商 Native 格式功能 (例如 `DateTime` 列时区元数据) 所使用的客户端协议版本。对于拒绝 `client_protocol_version` 的代理，请禁用此设置。
`max_error_size`	`1024`	任意非负整数	客户端错误中包含的最大字符数。使用 `0` 可获取完整消息。
`http_buffer_size`	`10485760`	字节	用于流式 HTTP 查询的内存中缓冲区大小，默认值为 10 MiB。

压缩

ClickHouse Connect 支持 lz4、zstd、brotli、gzip 和 deflate 响应压缩。Native insert 支持 lz4、zstd、brotli 和 gzip。压缩以增加 CPU time 开销为代价，减少网络传输量。

要接收压缩数据，ClickHouse server 的 enable_http_compression 必须设置为 1，或者用户必须具有按“每次查询”修改该设置的 permission。

压缩由传给 get_client 和 get_async_client 的 compress argument 控制。默认值 True 会声明所有可用的响应编码，并使用 lz4 压缩 Native insert 块。将 compress=False 可禁用压缩，或者传入 "lz4"、"zstd"、"br" 或 "gzip" 之一来请求特定 method。

原始 client methods 不使用 client 级别的 compress 设置。raw_query 和 raw_stream 返回未压缩数据，而 raw_insert 使用其自身的 compression argument 说明已应用于载荷的压缩方式。

ClickHouse Connect 安装时自带 lz4 和 zstd 支持。在 Python 3.14 上，zstd 使用标准库 compression.zstd module。Python 3.10 到 3.13 使用 backports.zstd。如果是未启用 zstd 支持构建的自定义 CPython 3.14+ 解释器，导入仍会成功；zstd 会从可用 methods 中移除，并且只有在显式请求 zstd 时才会引发 error。brotli 是可选项，使用 compress="br" 之前必须单独安装。

对于 ClickHouse workloads，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。

Variant、Dynamic 和 JSON 数据类型

ClickHouse Connect 支持当前 ClickHouse 的 Variant、Dynamic 和 JSON 数据类型。旧版 Object('json') 类型已在 clickhouse-connect 0.14 中移除，且不再受支持。

使用说明

Variant 值会按对应的 Python 类型读取。原生插入会根据 Python 值的类型选择成员。
当多个 Variant 成员映射到同一种 Python 类型时，使用 clickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName") 包装该值，以显式选择成员。
typed Variant 读取格式会返回 TypedVariant(value, type_name) 对象，并保留其原始成员类型。可通过 query_formats={"Variant": "typed"} 启用。
Dynamic 值会按对应的 Python 类型读取。插入目前通过 String 字符串表示形式发送。
JSON 值可作为 Python 字典或 JSON object 字符串插入。默认读取格式返回字典；使用 "string" 读取格式可返回 JSON 字符串。
选择 Variant、Dynamic 或 JSON 子列的查询会返回该子列的具体类型。

存储在 JSON 或 Dynamic 列的 shared-data 区域中的某些值使用了客户端目前尚无法解码的类型。这些值会以原始字节形式返回。这些复杂类型也会走纯 Python 转换路径，因此可能比成熟的标量类型更慢。