Uso avanzado

API directa

Para los casos de uso que no requieren transformar los datos de ClickHouse entre tipos y estructuras de datos nativos o de terceros, el cliente ClickHouse Connect proporciona métodos para usar directamente la conexión de ClickHouse.

Método `raw_query` de Client

El método Client.raw_query permite usar directamente la interfaz HTTP de consultas de ClickHouse a través de la conexión del cliente. El valor devuelto es un objeto bytes sin procesar. Proporciona un práctico envoltorio con enlace de parámetros, manejo de errores, reintentos y gestión de configuración mediante una interfaz mínima:

Parámetro	Tipo	Predeterminado	Descripción
`query`	str	Required	Cualquier consulta válida de ClickHouse.
`parameters`	dict or sequence	`None`	Consulte el argumento Parameters.
`settings`	dict	`None`	Consulte el argumento Settings.
`fmt`	str	`None`	Formato de salida de ClickHouse. ClickHouse usa TSV cuando no se especifica ningún formato.
`use_database`	bool	`True`	Incluye la base de datos configurada en el Client.
`external_data`	`ExternalData`	`None`	Archivo externo o datos binarios. Consulte Datos externos.
`transport_settings`	dict	`None`	Encabezados HTTP añadidos a esta solicitud.

Es responsabilidad de quien realiza la llamada procesar el objeto bytes resultante. Tenga en cuenta que Client.query_arrow es simplemente un envoltorio ligero sobre este método que usa el formato de salida Arrow de ClickHouse.

Método `raw_stream` de Client

El método síncrono Client.raw_stream tiene la misma API que raw_query, pero devuelve un flujo io.IOBase de fragmentos de bytes. Cierre el flujo cuando termine el procesamiento. AsyncClient.raw_stream debe esperarse con await y devuelve un StreamContext asíncrono para usar con async with y async for.

Método `raw_insert` de Client

El método Client.raw_insert permite realizar inserciones directas de objetos bytes o generadores de objetos bytes mediante la conexión del Client. Como no procesa la carga útil de la inserción, ofrece un rendimiento muy alto. El método proporciona opciones para especificar la configuración y el formato de inserción:

Parameter	Type	Default	Description
`table`	str	Required	El nombre simple de la tabla o el nombre de tabla calificado con la base de datos.
`column_names`	Sequence[str]	`None`	Nombres de columna para el bloque de inserción. Obligatorio cuando `fmt` no incluye nombres.
`insert_block`	str, bytes, generator, or `BinaryIO`	Required	Datos que se van a insertar. Las cadenas se codifican con la codificación del Client.
`settings`	dict	`None`	Consulte Settings argument.
`fmt`	str	`None`	Formato de entrada de ClickHouse de la carga útil de `insert_block`. Se usa `Native` cuando no se especifica ningún formato.
`compression`	str	`None`	Compresión ya aplicada a `insert_block`, como `"gzip"`, `"lz4"` o `"zstd"`.
`transport_settings`	dict	`None`	encabezados HTTP añadidos a esta solicitud.

Es responsabilidad de quien realiza la llamada garantizar que insert_block esté en el formato especificado y use el método de compresión indicado. ClickHouse Connect usa estas inserciones sin procesar para cargas de archivos y tablas de PyArrow, delegando el análisis en el servidor de ClickHouse.

Guardar los resultados de consultas como archivos

Puedes transferir archivos directamente desde ClickHouse al sistema de archivos local mediante el método raw_stream. Por ejemplo, si quieres guardar los resultados de una consulta en un archivo CSV, puedes usar el siguiente fragmento de código:

import clickhouse_connect

if __name__ == "__main__":
    client = clickhouse_connect.get_client()
    query = (
        "SELECT number, toString(number) AS number_as_str "
        "FROM system.numbers LIMIT 5"
    )
    stream = client.raw_stream(query=query, fmt="CSVWithNames")
    try:
        with open("output.csv", "wb") as file:
            for chunk in stream:
                file.write(chunk)
    finally:
        stream.close()
        client.close()

El código anterior genera un archivo output.csv con el siguiente contenido:

"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"

Del mismo modo, puede guardar datos en TabSeparated y en otros formatos. Consulte Formatos de entrada y salida de datos para ver un resumen de todas las opciones de formato disponibles.

Casos de uso multihilo, multiproceso y asíncronos/controlados por eventos

ClickHouse Connect funciona bien en aplicaciones multihilo, multiproceso y asíncronas/controladas por bucles de eventos. Todo el procesamiento de consultas e inserciones se realiza dentro de un único hilo, por lo que, en general, las operaciones son seguras en entornos multihilo. (El procesamiento en paralelo de algunas operaciones a bajo nivel es una posible mejora futura para superar la penalización de rendimiento de usar un único hilo, pero incluso en ese caso se mantendrá la seguridad en entornos multihilo). Como cada consulta o inserción ejecutada mantiene su estado en su propio objeto QueryContext o InsertContext, respectivamente, estos objetos auxiliares no son seguros en entornos multihilo y no deben compartirse entre varios flujos de procesamiento. Consulte información adicional sobre los objetos de contexto en las secciones QueryContexts e InsertContexts. Además, en una aplicación que tiene dos o más consultas y/o inserciones “en curso” al mismo tiempo, hay otras dos consideraciones que deben tenerse en cuenta. La primera es la “sesión” de ClickHouse asociada con la consulta o inserción, y la segunda es el pool de conexiones HTTP utilizado por las instancias de Client de ClickHouse Connect.

AsyncClient

ClickHouse Connect proporciona un Client nativo basado en aiohttp para aplicaciones con asyncio. Instala la dependencia opcional antes de usarlo:

pip install "clickhouse-connect[async]"

Aplica await a get_async_client para crear e inicializar un Client. Los métodos de E/S, como query, command e insert, son corrutinas:

import asyncio

import clickhouse_connect


async def main():
    async with await clickhouse_connect.get_async_client() as client:
        result = await client.query(
            "SELECT name FROM system.databases ORDER BY name LIMIT 1"
        )
        print(result.result_rows)


asyncio.run(main())

El Client asíncrono sigue el mismo contrato de consulta, insert, raw, Arrow y streaming que el Client síncrono. Usa aiohttp para el I/O de red. El parsing del formato Native, limitado por la CPU, puede ejecutarse en un executor para que no bloquee el bucle de eventos. Los métodos de streaming asíncronos se esperan con await antes de entrar en el contexto devuelto:

async with await client.query_rows_stream(
    "SELECT number FROM numbers(100000)"
) as stream:
    async for row in stream:
        process(row)

A diferencia de la factoría síncrona, get_async_client desactiva por defecto los ID de sesión automáticos para que las corrutinas concurrentes puedan compartir un Client. Pasa un session_id explícito o autogenerate_session_id=True solo cuando necesites estado de sesión y evites consultas concurrentes en esa sesión.

Administración de los ID de sesión de ClickHouse

Cada consulta de ClickHouse se realiza en el contexto de una “sesión” de ClickHouse. Actualmente, las sesiones se usan para dos fines:

Asociar ajustes de ClickHouse específicos con múltiples consultas (consulta los ajustes de usuario). El comando SET de ClickHouse se usa para cambiar los ajustes en el ámbito de una sesión de usuario.
Hacer seguimiento de las tablas temporales.

De forma predeterminada, un Client síncrono usa un ID de sesión generado. Por lo tanto, las sentencias SET y las tablas temporales persisten entre solicitudes de ese Client. La factoría async no genera un ID de sesión de forma predeterminada. ClickHouse no permite consultas concurrentes en la misma sesión, y el Client genera un ProgrammingError si se intenta, así que usa uno de los siguientes patrones:

Crea una instancia Client independiente para cada hilo/proceso/controlador de eventos que necesite aislamiento de sesión. Esto conserva el estado de sesión por Client (tablas temporales y valores de SET).
Usa un session_id único para cada consulta mediante el argumento settings al llamar a query, command o insert, si no necesitas un estado de sesión compartido.
Desactiva las sesiones en un Client compartido estableciendo autogenerate_session_id=False antes de crear el Client (o pásalo directamente a get_client).

import clickhouse_connect
from clickhouse_connect import common

common.set_setting("autogenerate_session_id", False)
client = clickhouse_connect.get_client(
    host="somehost.com",
    username="dbuser",
    password="password",
)

Como alternativa, pasa autogenerate_session_id=False directamente a get_client(...). En este caso, ClickHouse Connect no envía un session_id; el servidor no trata las solicitudes independientes como si pertenecieran a la misma sesión. Las tablas temporales y la configuración a nivel de sesión no persistirán entre solicitudes.

Personalización del grupo de conexiones HTTP

ClickHouse Connect usa grupos de conexiones de urllib3 para gestionar la conexión HTTP subyacente con el servidor. De forma predeterminada, todas las instancias de Client comparten el mismo grupo de conexiones, lo que resulta suficiente para la mayoría de los casos de uso. Este grupo predeterminado mantiene hasta 8 conexiones HTTP Keep Alive con cada servidor ClickHouse que utiliza la aplicación. En aplicaciones multihilo de gran tamaño, puede ser conveniente usar grupos de conexiones independientes. Se pueden proporcionar grupos de conexiones personalizados mediante el argumento de palabra clave pool_mgr de la función principal clickhouse_connect.get_client:

import clickhouse_connect
from clickhouse_connect.driver import httputil

big_pool_mgr = httputil.get_pool_manager(maxsize=16, num_pools=12)

client1 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)
client2 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)

Los Clients pueden compartir un gestor de grupos, o cada Client puede usar un gestor independiente. Para obtener más información, consulte la documentación de PoolManager de urllib3. El Client async tiene su propio grupo de aiohttp en lugar de usar urllib3. Configúrelo mediante connector_limit, connector_limit_per_host y keepalive_timeout en get_async_client. La llamada a await async_client.close_connections() rota el grupo sin interrumpir las solicitudes en curso.

Inicio

JavaScript

Python

Go

Java

C#

Rust

C++

C

Clientes de terceros

API directa

Método `raw_query` de Client

Método `raw_stream` de Client

Método `raw_insert` de Client

Guardar los resultados de consultas como archivos

Casos de uso multihilo, multiproceso y asíncronos/controlados por eventos

AsyncClient

Administración de los ID de sesión de ClickHouse

Personalización del grupo de conexiones HTTP

​API directa

​Método raw_query de Client

​Método raw_stream de Client

​Método raw_insert de Client

​Guardar los resultados de consultas como archivos

​Casos de uso multihilo, multiproceso y asíncronos/controlados por eventos

​AsyncClient

​Administración de los ID de sesión de ClickHouse

​Personalización del grupo de conexiones HTTP

API directa

Método `raw_query` de Client

Método `raw_stream` de Client

Método `raw_insert` de Client

Guardar los resultados de consultas como archivos

Casos de uso multihilo, multiproceso y asíncronos/controlados por eventos

AsyncClient

Administración de los ID de sesión de ClickHouse

Personalización del grupo de conexiones HTTP