> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse Connect 的其他选项

# 其他选项

ClickHouse Connect 提供了许多适用于高级用例的其他选项。

<div id="global-settings">
  ## 全局设置
</div>

有少量设置可用于全局控制 ClickHouse Connect 的行为。这些设置可通过顶层 `common` 包访问：

```python theme={null}
from clickhouse_connect import common

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

<Note>
  请在创建客户端前配置客户端创建设置。生成的会话/查询 ID、产品标识等设置会被复制到客户端专属状态中，因此之后对全局设置的更改不会更新现有客户端。绑定和插入设置则不同：绑定参数时会读取 `naive_datetime_binding` 和 `dict_parameter_format`；序列化包含 Python `datetime` 对象或 `DateTime64` ISO 字符串的原生插入列时，会读取 `naive_datetime_insert`。更改这些设置会影响现有客户端。可复用的插入上下文会在每次插入时使用当前的 `naive_datetime_insert` 值。
</Note>

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

| 设置名称                      | 默认值        | 选项                            | 描述                                                                                                                                                                                     |
| ------------------------- | ---------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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。                                                                                                                                                     |

<div id="compression">
  ## 压缩
</div>

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` 更慢。

<div id="http-proxy-support">
  ## HTTP 代理支持
</div>

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`。

<div id="variant-dynamic-json-data-types">
  ## Variant、Dynamic 和 JSON 数据类型
</div>

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

<div id="usage-notes">
  ### 使用说明
</div>

* `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 转换路径，因此可能比成熟的标量类型更慢。