> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Uso avanzado con ClickHouse Connect

# Uso avanzado

<div id="raw-api">
  ## API directa
</div>

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.

<div id="client-rawquery-method">
  ### Método `raw_query` de Client
</div>

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](/es/integrations/language-clients/python/driver-api#parameters-argument).                           |
| `settings`           | dict             | `None`         | Consulte [el argumento Settings](/es/integrations/language-clients/python/driver-api#settings-argument-1).                             |
| `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](/es/integrations/language-clients/python/advanced-querying#external-data). |
| `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.

<div id="client-rawstream-method">
  ### Método `raw_stream` de Client
</div>

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

<div id="client-rawinsert-method">
  ### Método `raw_insert` de Client
</div>

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](/es/integrations/language-clients/python/driver-api#settings-argument-1).                       |
| `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.

<div id="saving-query-results-as-files">
  ## Guardar los resultados de consultas como archivos
</div>

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:

```python theme={null}
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:

```csv theme={null}
"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"
```

Del mismo modo, puede guardar datos en [TabSeparated](/es/reference/formats/TabSeparated/TabSeparated) y en otros formatos. Consulte [Formatos de entrada y salida de datos](/es/reference/formats) para ver un resumen de todas las opciones de formato disponibles.

<div id="multithreaded-multiprocess-and-asyncevent-driven-use-cases">
  ## Casos de uso multihilo, multiproceso y asíncronos/controlados por eventos
</div>

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](/es/integrations/language-clients/python/advanced-querying#querycontexts) e [InsertContexts](/es/integrations/language-clients/python/advanced-inserting#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.

<div id="asyncclient">
  ## AsyncClient
</div>

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

```bash theme={null}
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:

```python theme={null}
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:

```python theme={null}
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.

<div id="managing-clickhouse-session-ids">
  ## Administración de los ID de sesión de ClickHouse
</div>

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](/es/reference/settings/session-settings)). 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.](/es/reference/statements/create/table#temporary-tables)

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:

1. 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`).
2. 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.
3. Desactiva las sesiones en un Client compartido estableciendo `autogenerate_session_id=False` antes de crear el Client (o pásalo directamente a `get_client`).

```python theme={null}
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.

<div id="customizing-the-http-connection-pool">
  ## Personalización del grupo de conexiones HTTP
</div>

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`:

```python theme={null}
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`](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#customizing-pool-behavior).

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.