API del driver ClickHouse Connect

API del driver ClickHouse Connect

Pase argumentos con nombre para las factorías de Client y los métodos con muchos parámetros opcionales.

Los métodos que no se documentan aquí no se consideran parte de la API y pueden eliminarse o modificarse.

​

Inicialización del Client

Utilice clickhouse_connect.get_client para crear un Client síncrono, o instale el extra async y espere clickhouse_connect.get_async_client para crear un AsyncClient nativo.

​

Argumentos de conexión

Parámetro	Tipo	Por defecto	Descripción
interface	str	"http"	"http" o "https". La factoría síncrona también acepta el backend experimental "chdb".
host	str	"localhost"	Nombre de host o dirección IP del servidor de ClickHouse.
port	int o None	8123 o 8443	El valor predeterminado es 8123 para HTTP y 8443 para HTTPS. Pasar None usa el valor predeterminado.
username	str o None	"default"	Nombre de usuario de ClickHouse. También se admiten los alias user y user_name.
password	str	""	Contraseña para username. No combine la autenticación por usuario/contraseña con la autenticación por token.
access_token	str o None	None	Token de acceso JWT de ClickHouse Cloud. Es incompatible con token_provider y con la autenticación mediante usuario/contraseña.
token_provider	callable o None	None	Callable que proporciona un JWT al principio y tras un rechazo de autenticación. Puede usarse un proveedor asíncrono con get_async_client.
database	str o None	Valor predeterminado del usuario	Base de datos predeterminada. Si se pasa None, se solicita la predeterminada del servidor para el usuario.
secure	bool o str	False	Habilita HTTPS/TLS. interface="https" también selecciona HTTPS, al igual que el puerto 443 o 8443 cuando no se establece interface.
dsn	str o None	None	URL de conexión. Los argumentos explícitos por palabra clave prevalecen sobre los valores analizados a partir del DSN. Aplique codificación porcentual a los caracteres reservados en las credenciales y los nombres de bases de datos.
settings	dict o None	None	Ajustes de ClickHouse aplicados a cada petición realizada por el client.
headers	dict o None	None	Encabezados HTTP aplicados a cada solicitud, incluida la inicialización del client. Los encabezados de usuario se aplican después de los valores predeterminados del driver y pueden sobrescribirlos.
compress	bool o str	True	Active la compresión o seleccione "lz4", "zstd", "br" o "gzip". Consulte Compression.
query_limit	int	0	Límite predeterminado de filas que se añade a las consultas aptas. Cero significa sin límite. Transmita los resultados grandes en lugar de materializarlos todos en memoria.
query_retries	int	2	Límite de reintentos para errores de lectura reintentables. Por lo general, los comandos y las inserciones no se reintentan, ya que repetirlas puede duplicar los efectos secundarios.
connect_timeout	int	10	Tiempo de espera de conexión en segundos.
send_receive_timeout	int	300	Tiempo de espera de lectura del socket en segundos.
client_name	str o None	None	Prefijo añadido al User-Agent de HTTP para su identificación en system.query_log.
session_id	str o None	Generado para síncrono	ID de sesión de ClickHouse explícito. Los client síncronos generan uno de forma predeterminada; los client async no lo hacen.
autogenerate_session_id	bool o None	Configuración global en sync, False en async	Sobrescribe la generación automática del ID de sesión. Desactívala en un client compartido por operaciones concurrentes, a menos que se requiera estado de sesión.
autogenerate_query_id	bool o None	Configuración global, True	Sobrescribe la generación automática del ID de consulta UUID.
http_proxy	str o None	Entorno/valor predeterminado	Dirección del proxy HTTP de cada client.
https_proxy	str o None	Entorno/valor predeterminado	Dirección del proxy HTTPS para cada client.
pool_mgr	urllib3.PoolManager o None	Valor predeterminado compartido	manager de grupo personalizado solo para el client síncrono.
tz_source	str o None	"auto"	Fuente de zona horaria de respaldo para columnas sin metadatos de zona horaria: "auto", "server" o "local".
tz_mode	str o None	"naive_utc"	Política para resultados en UTC: "naive_utc", "aware" o "schema". Consulte Zonas horarias.
show_clickhouse_errors	bool, cadena booleana, "scrub" o None	True	Controla str(exc) para errores del servidor, errores de transporte y StreamFailureError durante la transmisión. True incluye la URL de la solicitud y el sufijo con la versión del servidor. "scrub" conserva el texto del error SQL y el nombre simbólico, pero elimina el host/URL y el sufijo (version ...). False devuelve un mensaje genérico (code sigue establecido para los errores del servidor). Se aceptan cadenas booleanas. Otras cadenas generan ProgrammingError. Para los errores de transporte, __cause__ y los rastreos de pila siguen conteniendo la excepción de transporte original.
proxy_path	str	""	Prefijo de ruta añadido a la URL del servidor al enrutar a través de un proxy.
form_encode_query_params	bool	False	Coloca siempre los parámetros de consulta en el cuerpo de la solicitud codificado como formulario. Las cargas útiles de parámetros no binarios de gran tamaño se mueven automáticamente incluso cuando esto es false.
rename_response_column	str o None	None	Estrategia de cambio de nombre de columnas: "remove_prefix", "to_camelcase", "to_camelcase_without_prefix", "to_underscore" o "to_underscore_without_prefix".

La factoría asíncrona también acepta connector_limit=100, connector_limit_per_host=20 y keepalive_timeout=30.0 para configurar su grupo de conexiones de aiohttp. No acepta pool_mgr. El backend síncrono de chDB acepta path y chdb_options; consulta backend chDB integrado.

​

Argumentos de HTTPS/TLS

Parámetro	Tipo	Predeterminado	Descripción
verify	bool or str	True	Valida el certificado del servidor y el hostname. verify="proxy" habilita el modo TLS de proxy.
ca_cert	str or None	None	Ruta del paquete de CA. Usa "certifi" para seleccionar el paquete incluido en certifi.
client_cert	str or None	None	Certificado PEM del cliente, incluidos los certificados intermedios cuando sea necesario.
client_cert_key	str or None	None	Ruta de la clave privada cuando no está incluida en client_cert.
server_host_name	str or None	None	Hostname del certificado TLS/SNI cuando difiere de host, por ejemplo, a través de un túnel o un endpoint privado.
tls_mode	str or None	None	"mutual" usa la autenticación TLS mutua de ClickHouse. "proxy" y "strict" envían el certificado en la capa TLS sin habilitar los headers de autenticación por certificado de ClickHouse. El valor predeterminado None se comporta como "mutual" cuando se proporciona un certificado de cliente.

​

Argumento settings

Por último, el argumento settings de get_client se utiliza para pasar al servidor ajustes de ClickHouse adicionales en cada solicitud del Client. Ten en cuenta que, en la mayoría de los casos, los usuarios con acceso readonly=1 no pueden modificar los ajustes enviados con una consulta, por lo que ClickHouse Connect omitirá esos ajustes en la solicitud final y registrará una advertencia. Los siguientes ajustes solo se aplican a las consultas/sesiones HTTP que usa ClickHouse Connect y no están documentados como ajustes generales de ClickHouse.

Setting	Descripción
buffer_size	Tamaño del búfer de la respuesta HTTP del lado del servidor, en bytes.
session_id	ID de sesión utilizado para asociar solicitudes relacionadas. Es obligatorio para las tablas temporales y el estado de la sesión.
compress	Solicita al servidor que comprima una respuesta HTTP. Normalmente lo gestiona la opción de compresión del Client.
decompress	Indica al servidor que descomprima el cuerpo de la solicitud. Se usa para inserciones “raw” precomprimidas.
quota_key	La clave de cuota asociada a esta solicitud.
session_check	Solicita al servidor que valide que existe una sesión.
session_timeout	Tiempo de espera por inactividad de la sesión, en segundos.
wait_end_of_query	Almacena en búfer la respuesta completa en el servidor. El Client establece este ajuste cuando es necesario para la información de resumen no streaming.
query_id	ID de consulta explícito para la solicitud.
client_protocol_version	Nivel de capacidad del protocolo del Client para el formato nativo. Normalmente se negocia automáticamente.
role	Rol de ClickHouse que se usará para la solicitud/sesión.

Para ver otros ajustes de ClickHouse que pueden enviarse con cada consulta, consulta la documentación de ClickHouse.

​

Ejemplos de creación de clientes

• Sin parámetros, un cliente de ClickHouse Connect se conectará al puerto HTTP predeterminado en localhost, con el usuario default y sin contraseña:

import clickhouse_connect

client = clickhouse_connect.get_client()
print(client.server_version)

• Conectarse a un servidor externo de ClickHouse con HTTPS

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    secure=True,
    port=443,
    username="play",
    password="clickhouse",
)
print(client.command("SELECT timezone()"))

• Conectarse con un ID de sesión y otros parámetros de conexión personalizados, así como ajustes de ClickHouse.

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    username="play",
    password="clickhouse",
    port=443,
    secure=True,
    session_id="example_session_1",
    connect_timeout=15,
    database="github",
    settings={"distributed_ddl_task_timeout": 300},
)
print(client.database)
# Output: github

​

Backend integrado de chDB

Instala clickhouse-connect[chdb] para usar el backend experimental de chDB en el mismo proceso. Expone los métodos síncronos de consulta, insert, streaming y Arrow del Client:

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT sum(number) FROM numbers(10)")
    print(result.first_row)
    # Output: (45,)

De forma predeterminada, se usa una base de datos en memoria. Pase path="/data/my_chdb" o use dsn="chdb:///data/my_chdb" para contar con almacenamiento persistente. El backend permite una sola ruta de engine por proceso y no admite get_async_client ni datos externos.

​

Ciclo de vida del Client y buenas prácticas

Crear un Client de ClickHouse Connect es una operación costosa, ya que implica establecer una conexión, recuperar metadatos del servidor e inicializar el ajuste. Siga estas buenas prácticas para lograr un rendimiento óptimo:

​

Principios básicos

• Reutiliza los Clients: Crea los Clients una sola vez al iniciar la aplicación y reutilízalos durante toda su vida útil
• Evita crearlos con frecuencia: No crees un Client nuevo para cada consulta o solicitud
• Limpia correctamente: Cierra siempre los Clients al apagar la aplicación para liberar los recursos del grupo de conexiones
• Compártelos cuando sea posible: Un solo Client puede gestionar muchas consultas concurrentes a través de su grupo de conexiones (consulta las notas sobre hilos más abajo)

​

Patrones básicos

Reutiliza un único Client:

import clickhouse_connect

# Create once at startup
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)

# Reuse for all queries
for i in range(1000):
    result = client.query("SELECT count() FROM users")

# Close on shutdown
client.close()

Evita crear Clients repetidamente:

# BAD: Creates 1000 clients with expensive initialization overhead
for i in range(1000):
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    result = client.query("SELECT count() FROM users")
    client.close()

​

Aplicaciones multihilo

Las instancias de Client NO son seguras para subprocesos cuando se usan ID de sesión. De forma predeterminada, los Clients tienen un ID de sesión generado automáticamente, y las consultas concurrentes dentro de la misma sesión provocarán un ProgrammingError.

Para compartir un Client entre hilos de forma segura:

import clickhouse_connect
import threading

# Option 1: Disable sessions (recommended for shared clients)
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
    autogenerate_session_id=False,
)

def worker(thread_id):
    # All threads can now safely use the same client
    result = client.query(f"SELECT {thread_id}")
    print(f"Thread {thread_id}: {result.result_rows[0][0]}")

threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

client.close()

Alternativa para las sesiones: Si necesita sesiones (p. ej., para tablas temporales), cree un Client independiente por hilo:

def worker(thread_id):
    # Each thread gets its own client with isolated session
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    client.command("CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory")
    # ... use temp table ...
    client.close()

​

Limpieza adecuada

Cierra siempre los Clients al apagar el sistema. Ten en cuenta que client.close() elimina el Client y cierra las conexiones HTTP agrupadas solo cuando el Client tiene su propio administrador de grupos (por ejemplo, cuando se crea con opciones personalizadas de TLS/proxy). Para el grupo compartido predeterminado, usa client.close_connections() para limpiar proactivamente los sockets; de lo contrario, las conexiones se recuperan automáticamente por expiración por inactividad y al salir del proceso.

client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)
try:
    result = client.query("SELECT 1")
finally:
    client.close()

O bien, usa un administrador de contexto:

with clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
) as client:
    result = client.query("SELECT 1")

​

Cuándo usar varios clientes

Varios clientes son adecuados para:

• Servidores diferentes: un cliente por servidor o clúster de ClickHouse
• Credenciales diferentes: clientes separados para distintos usuarios o niveles de acceso
• Bases de datos diferentes: cuando necesite trabajar con varias bases de datos
• Sesiones aisladas: cuando necesite sesiones separadas para tablas temporales o ajustes específicos de la sesión
• Aislamiento por hilo: cuando los hilos necesiten sesiones independientes (como se muestra arriba)

​

Argumentos comunes de los métodos

Varios métodos del cliente usan uno o ambos argumentos comunes, parameters y settings. A continuación se describen estos argumentos de palabra clave.

​

Argumento parameters

Los métodos query* y command del cliente ClickHouse Connect aceptan un argumento opcional de palabra clave parameters, que se utiliza para vincular expresiones de Python a una expresión de valor de ClickHouse. Hay dos tipos de vinculación disponibles.

​

Vinculación del lado del servidor

ClickHouse admite la vinculación del lado del servidor para los valores de la consulta. El valor vinculado se envía por separado de la consulta como un parámetro HTTP. ClickHouse Connect usa este modo cuando detecta una expresión con el formato {<name>:<datatype>}. Pase los valores como un diccionario de Python.

Use None de Python para valores que admiten valores nulos. Se admiten valores None anidados dentro de parámetros Array y Tuple, y dentro de literales Map cuando dict_parameter_format se establece en "map".

• Vinculación del lado del servidor con diccionario de Python, valor DateTime y valor de cadena

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {
    "table": "my_table",
    "v1": my_date,
    "v2": "a string with a single quote'",
}
client.query(
    "SELECT * FROM {table:Identifier} "
    "WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
    parameters=parameters,
)

Esto equivale a:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

La vinculación del lado del servidor es compatible con las consultas SELECT. No funciona con ALTER, DELETE, INSERT ni con otros tipos de sentencias.

​

Vinculación en el cliente

ClickHouse Connect también admite la vinculación de parámetros en el cliente, lo que permite una mayor flexibilidad al generar consultas SQL con plantillas. Para la vinculación en el cliente, el argumento parameters debe ser un diccionario o una secuencia. La vinculación en el cliente utiliza el formato de cadenas estilo “printf” de Python para la sustitución de parámetros.

Ten en cuenta que, a diferencia de la vinculación del lado del servidor, la vinculación en el cliente no funciona con identificadores de bases de datos, como nombres de bases de datos, tablas o columnas, ya que el formato de estilo Python no puede distinguir entre los distintos tipos de cadenas y estos deben formatearse de forma diferente (backticks o comillas dobles para identificadores de bases de datos, comillas simples para valores de datos).

• Ejemplo con un diccionario de Python, un valor DateTime y escape de cadenas

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
    "SELECT * FROM my_table "
    "WHERE date >= %(v1)s AND string ILIKE %(v2)s",
    parameters=parameters,
)

Esto genera la siguiente consulta en el servidor:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

• Ejemplo con una secuencia de Python (Tuple), Float64 e IPv4Address

import ipaddress

parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
    "SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
    parameters=parameters,
)

Esto genera la siguiente consulta en el servidor:

SELECT *
FROM some_table
WHERE metric >= 35200.44
  AND ip_address = '68.61.4.254'

La vinculación de valores DateTime trata los valores sin zona horaria como hora de pared. El client formatea un datetime sin zona horaria literalmente. ClickHouse lo interpreta usando la zona horaria declarada en un placeholder del lado del servidor, como {dt:DateTime('Europe/Berlin')}, después session_timezone si está configurada y, por último, la zona horaria del servidor. Un datetime con zona horaria se convierte a la zona horaria declarada en el placeholder cuando está presente; de lo contrario, a la zona horaria del servidor indicada al momento de la conexión. Si la configuración session_timezone difiere de la zona horaria del servidor indicada, declare una zona horaria en el placeholder para mantener el instante previsto para los valores con zona horaria.

Para compatibilidad temporal con la conversión heredada de la hora local del host, establezca common.set_setting("naive_datetime_binding", "legacy") antes de vincular parámetros. Para preservar un instante, adjunte el tzinfo previsto al valor datetime antes de pasarlo como parámetro. Los inserts mediante client.insert interpretan de forma predeterminada los valores datetime sin zona horaria en la zona horaria local del proceso. Establezca la configuración global naive_datetime_insert en "server" para interpretarlos como hora de pared en la zona horaria de la columna o, si la columna no tiene ninguna, en la zona horaria del servidor. Consulte Objetos datetime sin zona horaria.

Para un placeholder {value:DateTime64(precision)} del lado del servidor, el tipo declarado conserva automáticamente la precisión de fracciones de segundo, incluso dentro de las pistas Array y Tuple.

La vinculación %s en el cliente no tiene un tipo declarado. Envuelva un datetime en DT64Param cuando deba representarse con precisión de fracciones de segundo:

from datetime import datetime

from clickhouse_connect.driver.binding import DT64Param

query = "SELECT toDateTime64(%s, 6)"
parameters = [DT64Param(datetime.now())]
client.query(query, parameters=parameters)

Por compatibilidad con versiones anteriores, un nombre de parámetro de diccionario que termina en _64 también solicita el formato DateTime64 cuando ese nombre exacto con sufijo no está presente en la consulta.

Un parámetro datetime.time o datetime.timedelta se formatea como un literal [-]HH:MM:SS[.ffffff] para las columnas Time y Time64 de ClickHouse, en ambos estilos de vinculación y dentro de valores Array y Tuple. El client añade las comillas, así que no incluya el placeholder entre comillas en la consulta. Un timedelta puede ser negativo y superar las 24 horas. Un Timedelta de pandas conserva sus nanosegundos y se formatea con una fracción de nueve dígitos para Time64(9). La información de zona horaria de un time con zona horaria se ignora porque Time de ClickHouse no tiene zona horaria.

​

Argumento settings

Todos los métodos principales “insert” y “select” del cliente ClickHouse Connect aceptan un argumento de palabra clave opcional, settings, para pasar ajustes de usuario del servidor ClickHouse a la sentencia SQL incluida. El argumento settings debe ser un diccionario. Cada elemento debe contener el nombre de un ajuste de ClickHouse y su valor asociado. Ten en cuenta que los valores se convertirán en cadenas al enviarse al servidor como parámetros de consulta.

Al igual que con los ajustes a nivel de cliente, ClickHouse Connect descartará cualquier ajuste que el servidor marque como readonly=1, con el correspondiente mensaje de log. Los ajustes que se aplican solo a consultas a través de la interfaz HTTP de ClickHouse siempre son válidos. Esos ajustes se describen en la API get_client.

Ejemplo de uso de ajustes de ClickHouse:

settings = {
    "merge_tree_min_rows_for_concurrent_read": 65535,
    "session_id": "session_1234",
    "use_skip_indexes": False,
}
client.query(
    "SELECT event_type, sum(timeout) "
    "FROM event_errors WHERE event_time > '2022-08-01'",
    settings=settings,
)

​

Método command del Client

Use Client.command para sentencias que no devuelven un conjunto de datos tabular, o para consultas que devuelven un valor primitivo o una fila. Según la respuesta, devuelve una cadena, un entero, una secuencia de cadenas o QuerySummary. Una lectura que produce un conjunto de resultados vacío devuelve una cadena vacía.

Parámetro	Tipo	Predeterminado	Descripción
cmd	str	Obligatorio	Una sentencia de ClickHouse SQL que devuelve un único valor o una única fila de valores.
parameters	dict or sequence	None	Consulte la descripción de los parámetros.
data	str or bytes	None	Datos opcionales para incluir con el comando como cuerpo de la solicitud POST.
settings	dict	None	Consulte la descripción del ajuste.
use_database	bool	True	Usa la base de datos del Client (especificada al crear el Client). False significa que el comando usará la base de datos predeterminada del servidor de ClickHouse para el usuario conectado.
external_data	ExternalData	None	Un objeto ExternalData que contiene datos de archivo o binarios para usar con la consulta. Consulte Advanced Queries (External Data)
transport_settings	dict	None	Diccionario opcional de encabezados HTTP para incluir con esta solicitud. Cada par clave-valor se añade como un encabezado HTTP (p. ej., {'X-Custom-Header': 'value'}). Resulta útil para la autenticación del proxy, el tracing de solicitudes o para pasar encabezados requeridos por la infraestructura intermedia.

​

Ejemplos del comando

​

Sentencias DDL

import clickhouse_connect

client = clickhouse_connect.get_client()

# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
    "CREATE TABLE test_command "
    "(col_1 String, col_2 DateTime) "
    "ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())

# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
#     `col_1` String,
#     `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()

# Drop table
client.command("DROP TABLE test_command")

​

Consultas sencillas que devuelven valores individuales

import clickhouse_connect

client = clickhouse_connect.get_client()

# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)

# Server version
version = client.command("SELECT version()")
print(version)

​

Comandos con parámetros

import clickhouse_connect

client = clickhouse_connect.get_client()

# Usando parámetros del lado del cliente
table_name = "system"
result = client.command(
    "SELECT count() FROM system.tables WHERE database = %(db)s",
    parameters={"db": table_name}
)

# Usando parámetros del lado del servidor
result = client.command(
    "SELECT count() FROM system.tables WHERE database = {db:String}",
    parameters={"db": "system"}
)

​

Comandos con ajustes

import clickhouse_connect

client = clickhouse_connect.get_client()

# Ejecutar comando con configuraciones específicas
result = client.command(
    "OPTIMIZE TABLE large_table FINAL",
    settings={"optimize_throw_if_noop": 1}
)

​

Método query de Client

Client.query recupera un conjunto de datos tabular en formato Native de ClickHouse y devuelve un QueryResult. El resultado completo se materializa al acceder a una propiedad del resultado. Use un método de streaming para resultados que no deban mantenerse en memoria.

Parámetro	Tipo	Predeterminado	Descripción
query	str	Required	consulta de ClickHouse que devuelve un resultado tabular, normalmente SELECT o DESCRIBE. Puede omitirse cuando se proporciona mediante context.
parameters	dict or sequence	None	Consulte Parameters argument.
settings	dict	None	Consulte Settings argument.
query_formats	dict	None	Formato de lectura por tipo de ClickHouse. Consulte Read formats.
column_formats	dict	None	Formato de lectura por columna del resultado, incluidas las correspondencias de formato para Nested type.
encoding	str	None	Codificación de columna String. El valor predeterminado es UTF-8.
use_none	bool	True	Devuelve None para SQL NULL. Cuando es false, devuelve el valor nulo predeterminado del tipo. Los methods de NumPy/Pandas eligen valores predeterminados orientados al rendimiento.
column_oriented	bool	False	Orienta el resultado por columnas en lugar de por filas.
use_numpy	bool	False	Lee las columnas de resultado compatibles en arrays de NumPy dentro de QueryResult. Prefiera query_np cuando el resultado deseado sea una sola matriz de NumPy.
max_str_len	int	0	Con use_numpy, usa un dtype Unicode de ancho fijo para columna String de hasta esta longitud. Cero usa arrays de objetos.
context	QueryContext	None	Contexto de consulta reutilizable. Los argumentos explícitos del método prevalecen sobre los valores del contexto.
query_tz	str or tzinfo	None	Zona horaria aplicada a todas las columnas de resultado DateTime y DateTime64.
column_tzs	dict	None	correspondencia de zona horaria por columna.
external_data	ExternalData	None	Archivo externo o datos binarios. Consulte External data.
transport_settings	dict	None	HTTP headers añadidos a esta solicitud.
tz_mode	str	Client default	sobrescritura por consulta para el manejo de zona horaria "naive_utc", "aware" o "schema".

​

Ejemplos de consultas

​

Consulta básica

import clickhouse_connect

client = clickhouse_connect.get_client()

# Simple SELECT query
result = client.query(
    "SELECT number, toString(number) AS label FROM numbers(3)"
)

# Access results as rows
for row in result.result_rows:
    print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')

# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']

​

Acceder a los resultados de la consulta

import clickhouse_connect

client = clickhouse_connect.get_client()

result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")

# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]

# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]

# Named results (list of dictionaries)
for row_dict in result.named_results():
    print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}

# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}

# First row as tuple
print(result.first_row)
# Output: (0, '0')

​

Consulta con parámetros en el cliente

import clickhouse_connect

client = clickhouse_connect.get_client()

# Uso de parámetros de diccionario (estilo printf)
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)

# Uso de parámetros de tupla
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)

​

Consulta con parámetros del servidor

import clickhouse_connect

client = clickhouse_connect.get_client()

# Vinculación del lado del servidor (más segura, mejor rendimiento para consultas SELECT)
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}

result = client.query(query, parameters=parameters)

​

Consulta con ajustes

import clickhouse_connect

client = clickhouse_connect.get_client()

# Pasa los ajustes de ClickHouse con la consulta
result = client.query(
    "SELECT sum(number) FROM numbers(1000000)",
    settings={
        "max_block_size": 100000,
        "max_execution_time": 30
    }
)

​

El objeto QueryResult

El método base query devuelve un objeto QueryResult con las siguientes propiedades públicas:

• result_rows — Matriz de resultados orientada por filas.
• result_columns — Matriz de resultados orientada por columnas.
• result_set — result_rows o result_columns, según la orientación de la consulta.
• column_names — Tuple con los nombres de las columnas del resultado.
• column_types — Tuple de objetos ClickHouseType.
• row_count — Número de filas de resultados materializadas.
• query_id — ID de consulta informado o generado para la solicitud. Una cadena vacía significa que no había ninguno disponible.
• summary — Diccionario decodificado del header de respuesta X-ClickHouse-Summary.
• first_item — Primera fila como diccionario, o None si el resultado está vacío.
• first_row — Primera fila como secuencia, o None si el resultado está vacío.
• column_block_stream, row_block_stream y rows_stream — Contextos internos de stream. Use en su lugar los métodos de streaming correspondientes del Client.

Consulte Consultas en streaming para conocer las API de StreamContext compatibles.

​

Consumo de resultados de consultas con NumPy, Pandas o Arrow

ClickHouse Connect proporciona métodos de consulta específicos para trabajar con los formatos de datos NumPy, Pandas y Arrow. Para obtener información detallada sobre cómo usar estos métodos, incluidos ejemplos, streaming y gestión avanzada de tipos, consulte Consultas avanzadas (consultas de NumPy, Pandas y Arrow).

​

Métodos del cliente para consultas en streaming

Para transmitir grandes conjuntos de resultados, ClickHouse Connect ofrece varios métodos de streaming. Consulta Consultas avanzadas (Streaming Queries) para obtener más información y ejemplos.

​

Método insert del Client

Para el caso de uso habitual de insertar varios registros en ClickHouse, está el método Client.insert. Acepta los siguientes parámetros:

Parámetro	Tipo	Predeterminado	Descripción
table	str	Required	Tabla de destino. Se permite un nombre completo con la base de datos. Puede omitirse cuando lo proporciona context.
data	Sequence of Sequences	Required	Matriz de datos orientada a filas o orientada a columna. Puede proporcionarse más adelante mediante un InsertContext.
column_names	str or Sequence[str]	"*"	Columnas ordenadas. "*" ejecuta una consulta de metadatos para detectar todas las columnas insertables.
database	str or None	Base de datos del Client	Base de datos de destino cuando table no está calificada.
column_types	Sequence[ClickHouseType]	None	Tipos de columna explícitos. Evita la consulta de metadatos cuando se proporcionan.
column_type_names	Sequence[str]	None	Nombres de tipos de ClickHouse explícitos. Alternativa a column_types.
column_oriented	bool	False	Interpreta data como columnas en lugar de filas.
settings	dict	None	Consulte argumento Settings.
context	InsertContext	None	Contexto de inserción reutilizable. Consulte InsertContexts.
transport_settings	dict	None	headers HTTP añadidos a esta solicitud.

Este método devuelve QuerySummary. Su diccionario summary contiene valores informados por el server. written_rows es una propiedad de conveniencia, mientras que written_bytes() y query_id() devuelven los valores correspondientes. Un fallo en la inserción genera una excepción.

Para métodos de inserción especializados que funcionan con Pandas DataFrames, tablas PyArrow y DataFrames respaldados por Arrow, consulte Inserciones avanzadas (Métodos de inserción especializados).

Una matriz de NumPy es una Sequence of Sequences válida y puede usarse como argumento data para el método principal insert, por lo que no se requiere un método especializado.

​

Ejemplos

Los ejemplos a continuación suponen que existe una tabla users con el esquema (id UInt32, name String, age UInt8).

​

Inserción básica por filas

import clickhouse_connect

client = clickhouse_connect.get_client()

# Row-oriented data: each inner list is a row
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert("users", data, column_names=["id", "name", "age"])

​

Inserción orientada a columnas

import clickhouse_connect

client = clickhouse_connect.get_client()

# Column-oriented data: each inner list is a column
data = [
    [13, 79],  # id column
    ["user_1", "user_2"],  # name column
    [25, 30],  # age column
]

client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)

​

Inserción con tipos explícitos de columnas

import clickhouse_connect

client = clickhouse_connect.get_client()

# Useful when you want to avoid a DESCRIBE query to the server
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    column_type_names=["UInt32", "String", "UInt8"],
)

​

Insertar en una base de datos específica

import clickhouse_connect

client = clickhouse_connect.get_client()

data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

# Insert into a table in a specific database
client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    database="production",
)

​

Inserciones desde archivos

Para insertar datos directamente desde archivos en tablas de ClickHouse, consulte Inserción avanzada (Inserciones desde archivos).

​

API en bruto

Para casos de uso avanzados que requieran acceso directo a las interfaces HTTP de ClickHouse sin transformaciones de tipos, consulte Uso avanzado (Raw API).

​

Python DB-API 2.0

El módulo clickhouse_connect.dbapi implementa la interfaz de conexión y cursor definida por PEP 249. Declara el nivel de API 2.0, threadsafety=2 y paramstyle="pyformat". El módulo también proporciona los constructores de tipos PEP 249 Date, Time, Timestamp y Binary, y las funciones DateFromTicks, TimeFromTicks y TimestampFromTicks.

from clickhouse_connect import dbapi

connection = dbapi.connect(
    host="localhost",
    username="default",
    password="password",
    database="default",
)
cursor = connection.cursor()

try:
    cursor.execute(
        "SELECT name FROM system.tables "
        "WHERE database = %(database)s ORDER BY name LIMIT 5",
        {"database": "system"},
    )
    print(cursor.description)
    print(cursor.fetchall())
finally:
    cursor.close()
    connection.close()

Cursor.execute y Cursor.executemany aceptan argumentos adicionales de palabra clave, settings y query_formats. settings pasa ajustes de ClickHouse. query_formats aplica formatos de lectura según el tipo de ClickHouse cuando una sentencia devuelve filas, usando la misma correspondencia que Client.query. executemany usa la ruta nativa de inserción masiva del driver para las sentencias INSERT ... VALUES compatibles con una secuencia materializada de filas. fetchone, fetchmany y fetchall consumen el resultado materializado actual.

Cursor.description deriva null_ok del tipo de cada columna de resultado. Los tipos que no admiten valores NULL informan False, y los tipos que admiten valores NULL informan True, incluidos los envoltorios Nullable, Variant y Dynamic. None significa que se desconoce la nulabilidad. Cuando una consulta que comienza con SELECT o WITH, ignorando los comentarios iniciales, no devuelve filas ni metadatos de columnas, el cursor ejecuta una consulta de metadatos LIMIT 0 para poblar description. Si esa consulta de metadatos falla, description se deja vacío.

ClickHouse no proporciona transacciones tradicionales a través de esta interfaz HTTP. Connection.commit() y Connection.rollback() no tienen efecto. Las reglas de concurrencia del ID de sesión siguen aplicándose cuando se comparte una conexión.

​

Clases y funciones de utilidad

Los siguientes módulos proporcionan funciones auxiliares públicas adicionales que usan las aplicaciones Client.

La versión del paquete instalado se expone como la cadena clickhouse_connect.__version__.

​

Excepciones

Las excepciones personalizadas, incluida la jerarquía de excepciones de DB-API 2.0, se definen en clickhouse_connect.driver.exceptions. DatabaseError y OperationalError exponen un atributo numérico code con el código de error de ClickHouse y un atributo name con el nombre simbólico, como UNKNOWN_TABLE, para que las aplicaciones puedan basarse en exc.code en lugar de tener que analizar el mensaje. code se establece incluso cuando show_clickhouse_errors está deshabilitado, mientras que name requiere detalles del error (True o "scrub"). Ambos son None cuando no están disponibles, por ejemplo, en errores de transporte. Use show_clickhouse_errors="scrub" cuando los usuarios finales deban ver errores de SQL sin información del host ni de la versión del servidor. Esta configuración también controla los mensajes de StreamFailureError durante la transmisión y los mensajes de transporte genéricos. Solo afecta a str(exc). Los errores de transporte siguen adjuntos como __cause__, y los seguimientos de pila pueden contener el texto original del error del host, la URL o la biblioteca.

​

Utilidades de ClickHouse SQL

Las funciones y la clase DT64Param del módulo clickhouse_connect.driver.binding pueden usarse para construir y escapar correctamente consultas en ClickHouse SQL. Del mismo modo, las funciones del módulo clickhouse_connect.driver.parser pueden usarse para analizar nombres de tipos de datos de ClickHouse.

​

Casos de uso multihilo, multiproceso y asíncronos/orientados a eventos

Para obtener información sobre el uso de ClickHouse Connect en aplicaciones multihilo, multiproceso y asíncronas/orientadas a eventos, consulte Uso avanzado (casos de uso multihilo, multiproceso y asíncronos/orientados a eventos).

​

AsyncClient

Para obtener información sobre el uso nativo de asyncio, consulte Uso avanzado (AsyncClient).

​

Gestión de los IDs de sesión de ClickHouse

Para obtener información sobre cómo gestionar los IDs de sesión de ClickHouse en aplicaciones multihilo o concurrentes, consulte Uso avanzado (Gestión de los IDs de sesión de ClickHouse).

​

Personalización del pool de conexiones HTTP

Para obtener información sobre cómo personalizar el pool de conexiones HTTP para aplicaciones grandes con varios hilos, consulte Uso avanzado (Personalización del pool de conexiones HTTP).