Configuración global
common de nivel superior:
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.Compresión
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
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
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
Variantse 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
Variantse asignan al mismo tipo de Python, envuelva el valor conclickhouse_connect.datatypes.dynamic.typed_variant(value, "TypeName")para seleccionar el miembro de forma explícita. - El formato de lectura
typeddeVariantdevuelve objetosTypedVariant(value, type_name)y conserva el tipo del miembro de origen. Habilítelo conquery_formats={"Variant": "typed"}. - Los valores de
Dynamicse leen como el tipo de Python correspondiente. Actualmente, las inserciones se envían mediante la representación String. - Los valores de
JSONpueden 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,DynamicoJSONdevuelven el tipo concreto de la subcolumna.
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.