API del driver ClickHouse Connect

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.

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.

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.

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

• 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

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.

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:

• 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)

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()

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()

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")

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)

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

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.

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.

Los nombres de los parámetros deben ser nombres BareWord ASCII de ClickHouse. El driver acepta $ al inicio, dentro o al final del nombre cuando el servidor lo acepta, como en {$tenant_id:String}. Una clave de diccionario que comienza y termina con $ y tiene un valor de búfer como bytes, bytearray o memoryview está reservada para la convención de parámetros binarios sin procesar de ClickHouse Connect. Si dicha clave se utiliza para un parámetro del lado del servidor no binario, limítela a un único placeholder {name:Type}. Los nombres $tag$ repetidos pueden ser interpretados por ClickHouse como marcadores heredoc.

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\''

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'

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,
)

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.

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")

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)

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"}
)

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}
)

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.

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']

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')

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)

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)

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 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.

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).

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.

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

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).

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

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"])

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)

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"],
)

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",
)

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

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

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. Cursor.execute también acepta el argumento exclusivo de palabra clave pyformat_encoded. Su valor predeterminado, True, se ajusta al contrato pyformat de DB-API. El dialecto SQLAlchemy lo establece en False cuando el compilador de sentencias emitió signos de porcentaje sin procesar, por lo que normalmente las aplicaciones no deberían establecerlo. 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.

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__.

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.

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.

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).

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

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).

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).