> ## 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.
> Opciones adicionales para ClickHouse Connect
# Opciones adicionales
ClickHouse Connect ofrece varias opciones adicionales para casos de uso avanzados.
## Configuración global
Hay algunos ajustes que controlan globalmente el comportamiento de ClickHouse Connect. Se accede a ellos desde el paquete `common` de nivel superior:
```python theme={null}
from clickhouse_connect import common
common.set_setting("autogenerate_session_id", False)
print(common.get_setting("invalid_setting_action"))
# Output: error
```
Configure los ajustes de creación de Clients antes de crear los Clients. Los ajustes, como los ID de sesión/consulta generados y la identificación del producto, se copian en el estado específico de cada Client, por lo que los cambios globales posteriores no actualizan los Clients existentes. Los ajustes de vinculación e inserción funcionan de forma diferente. `naive_datetime_binding` y `dict_parameter_format` se leen al vincular los parámetros. `naive_datetime_insert` se lee al serializar una columna de inserción nativa que contiene objetos `datetime` de Python o cadenas ISO `DateTime64`. Los cambios en estos ajustes afectan a los Clients existentes. Un contexto de inserción reutilizable usa el valor actual de `naive_datetime_insert` en cada inserción.
Actualmente están definidos los siguientes ajustes globales:
| Nombre del ajuste | Predeterminado | Opciones | Descripción |
| ------------------------- | -------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autogenerate_session_id` | `True` | `True`, `False` | Genera un ID de sesión UUID para cada Client síncrono, salvo que se proporcione uno. La fábrica asíncrona establece este valor en `False` de forma predeterminada. |
| `autogenerate_query_id` | `True` | `True`, `False` | Genera un ID de consulta UUID para cada solicitud, salvo que se proporcione uno. |
| `dict_parameter_format` | `"json"` | `"json"`, `"map"` | Da formato JSON o de literal Map de ClickHouse a los diccionarios de Python usados en la vinculación de parámetros. |
| `invalid_setting_action` | `"error"` | `"drop"`, `"send"`, `"error"` | Acción que se realiza cuando el servidor informa de que un ajuste es readonly. `drop` lo ignora, `send` lo reenvía y `error` genera un `ProgrammingError`. Los ajustes que no aparecen en `system.settings` para el usuario actual, como uno configurado como `CHANGEABLE_IN_READONLY` en un rol, se reenvían para que el servidor pueda aceptarlos o rechazarlos, a menos que la acción sea `drop`. |
| `naive_datetime_binding` | `"wall"` | `"wall"`, `"legacy"` | Controla la vinculación de parámetros de consulta `datetime` sin zona horaria. `wall` formatea literalmente los valores datetime sin zona horaria. `legacy` restaura el comportamiento anterior de conversión según la zona horaria local del host. Adjunte `tzinfo` para preservar un instante concreto. |
| `naive_datetime_insert` | `"local"` | `"local"`, `"server"` | Controla las inserciones de objetos Python de valores `datetime` sin zona horaria y cadenas ISO sin zona horaria aceptadas por `DateTime64`. `local` usa la zona horaria del proceso por compatibilidad. `server` usa la zona horaria declarada de la columna y, después, la zona horaria del servidor. Las columnas NumPy y Pandas con dtype `datetime64` no cambian. |
| `max_connection_age` | `600` | Cualquier número de segundos | Antigüedad máxima de una conexión HTTP keep-alive reutilizada. La rotación ayuda a distribuir las conexiones entre los nodos situados detrás de un balanceador de carga. |
| `product_name` | `""` | Cualquier cadena | Identificador de producto añadido a la información del Client. Use un valor como `"my-product/1.0"`. |
| `readonly` | `0` | `0`, `1` | Operación obsoleta sin efecto, conservada por compatibilidad con 1.x. El Client lee directamente el ajuste `readonly` del servidor. |
| `send_os_user` | `True` | `True`, `False` | Incluye el usuario detectado del sistema operativo en la información del Client. |
| `send_integration_tags` | `True` | `True`, `False` | Incluye en el User-Agent HTTP las integraciones usadas por el Client, como Pandas o SQLAlchemy. |
| `use_protocol_version` | `True` | `True`, `False` | Negocia la versión del protocolo de Client utilizada por funciones del formato Native, como los metadatos de zona horaria de las columnas `DateTime`. Desactive esta opción para proxies que rechacen `client_protocol_version`. |
| `max_error_size` | `1024` | Cualquier entero no negativo | Número máximo de caracteres incluidos en un error del Client. Use `0` para el mensaje completo. |
| `http_buffer_size` | `10485760` | Bytes | Tamaño del búfer en memoria para consultas HTTP de streaming; el valor predeterminado es 10 MiB. |
## Compresión
ClickHouse Connect admite compresión de respuestas con lz4, zstd, brotli, gzip y deflate. Las inserciones Native admiten lz4, zstd, brotli y gzip. La compresión reduce la transferencia de red a costa de tiempo de CPU.
Para recibir datos comprimidos, en el servidor ClickHouse `enable_http_compression` debe establecerse en 1, o el usuario debe tener permiso para cambiar esta configuración para cada consulta.
La compresión se controla mediante el argumento `compress` de `get_client` y `get_async_client`. El valor predeterminado, `True`, anuncia todas las codificaciones de respuesta disponibles y comprime los bloques de inserción Native con lz4. Establezca `compress=False` para desactivar la compresión, o pase uno de `"lz4"`, `"zstd"`, `"br"` o `"gzip"` para solicitar un método específico.
Los métodos raw del client no usan la configuración `compress` a nivel de client. `raw_query` y `raw_stream` devuelven datos sin comprimir, y `raw_insert` usa su propio argumento `compression` para indicar la compresión ya aplicada al payload.
La compatibilidad con lz4 y zstd se instala con ClickHouse Connect. En Python 3.14, zstd usa el módulo `compression.zstd` de la biblioteca estándar. Python 3.10 a 3.13 usa `backports.zstd`. Un intérprete CPython 3.14+ personalizado compilado sin compatibilidad con zstd sigue pudiéndose importar; zstd se elimina de los métodos disponibles y solo se genera un error cuando se solicita zstd explícitamente. Brotli es opcional y debe instalarse por separado antes de usar `compress="br"`.
gzip suele ser más lento que lz4 o zstd para las cargas de trabajo de ClickHouse.
## Compatibilidad con proxy HTTP
ClickHouse Connect reconoce las variables de entorno estándar `HTTP_PROXY` y `HTTPS_PROXY`. Estas variables se aplican a todos los client del proceso. Para configurar un proxy por client, pase `http_proxy` o `https_proxy` a `get_client` o `get_async_client`.
El client síncrono usa `urllib3`. Para usar un proxy SOCKS, instale PySocks y pase un `urllib3.contrib.socks.SOCKSProxyManager` como argumento `pool_mgr` a `get_client`. `pool_mgr` no es compatible con el client asíncrono.
## Tipos de datos Variant, Dynamic y JSON
ClickHouse Connect admite los tipos actuales `Variant`, `Dynamic` y `JSON` de ClickHouse. El tipo heredado `Object('json')` se eliminó en clickhouse-connect 0.14 y no es compatible.
### Notas de uso
* Los valores de `Variant` se leen como el tipo de Python correspondiente. Las inserciones Native seleccionan un miembro en función del tipo de valor de Python.
* Cuando varios miembros de `Variant` se asignan al mismo tipo de Python, envuelva el valor con `clickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName")` para seleccionar el miembro de forma explícita.
* El formato de lectura `typed` de `Variant` devuelve objetos `TypedVariant(value, type_name)` y conserva el tipo del miembro de origen. Habilítelo con `query_formats={"Variant": "typed"}`.
* Los valores de `Dynamic` se leen como el tipo de Python correspondiente. Actualmente, las inserciones se envían mediante la representación String.
* Los valores de `JSON` pueden insertarse como diccionarios de Python o como cadenas que contienen objetos JSON. El formato de lectura predeterminado devuelve diccionarios; use el formato de lectura `"string"` para devolver cadenas JSON.
* Las consultas que seleccionan una subcolumna de `Variant`, `Dynamic` o `JSON` devuelven el tipo concreto de la subcolumna.
Algunos valores almacenados en el área `shared-data` de las columnas `JSON` o `Dynamic` usan tipos que el client aún no puede decodificar. Esos valores se devuelven como bytes sin procesar. Estos tipos complejos también usan la ruta de conversión de pure Python, por lo que pueden ser más lentos que los tipos escalares ya consolidados.