Opciones adicionales | ClickHouse Docs

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:

from clickhouse_connect import common

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

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.