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

> O pacote de projetos ClickHouse Connect para conectar Python ao ClickHouse

# Introdução

ClickHouse Connect é um driver principal de banco de dados que oferece interoperabilidade com uma ampla variedade de aplicações em Python.

* As principais interfaces são o `Client` síncrono e o `AsyncClient`, nativo e baseado em aiohttp, em `clickhouse_connect.driver`. O pacote do driver também fornece contextos de consulta e insert, utilitários de streaming, suporte a DB-API e métodos HTTP de nível mais baixo.
* O pacote `clickhouse_connect.datatypes` serializa e desserializa tipos do ClickHouse usando o formato colunar binário Native do ClickHouse.
* As extensões opcionais em Cython em `clickhouse_connect.driverc` aceleram caminhos comuns de serialização, conversão e bufferização. Uma implementação em Python puro continua disponível em plataformas nas quais as extensões não podem ser compiladas.
* O pacote inclui informações de tipos do PEP 561, para que verificadores de tipo downstream consumam anotações para as interfaces públicas do driver, da DB-API e do SQLAlchemy.
* O dialeto do [SQLAlchemy](https://www.sqlalchemy.org/) em `clickhouse_connect.cc_sqlalchemy` oferece suporte ao SQLAlchemy Core, reflexão de esquema, cláusulas de consulta específicas do ClickHouse e motores de tabela, além de migrações do Alembic. Leituras e inserts básicos com ORM funcionam, mas o dialeto foi projetado para workloads analíticas, e não para o comportamento ORM completo de unit-of-work.
* O driver principal e a implementação [ClickHouse Connect SQLAlchemy](/pt-BR/integrations/language-clients/python/sqlalchemy) são o método preferido para conectar o ClickHouse ao Apache Superset. Use a conexão de banco de dados `ClickHouse Connect` ou a string de conexão do dialeto SQLAlchemy `clickhousedb`.

Esta documentação está atualizada até a versão 1.6.0 do clickhouse-connect. Se você estiver atualizando da versão 0.15.x ou anterior, consulte o [guia de migração 1.0](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md).

<Note>
  Os clientes padrão do ClickHouse Connect usam a interface HTTP. Isso oferece suporte a balanceadores de carga HTTP, proxies e controles de rede corporativos comuns. O ClickHouse Connect também tem um backend [chDB](#embedded-chdb-backend) experimental in-process.
</Note>

<div id="requirements-and-compatibility">
  ## Requisitos e compatibilidade
</div>

| Componente  | Versões compatíveis                                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| Python      | 3.10 a 3.14. Compilações free-threaded, como 3.14t, têm suporte experimental.                                         |
| ClickHouse  | Lançamentos do ClickHouse com suporte ativo. A CI realiza testes com lançamentos recentes LTS e estáveis do servidor. |
| SQLAlchemy  | 1.4.40 ou posterior, abaixo de 3.0                                                                                    |
| Pandas      | 2.x e 3.x                                                                                                             |
| Polars      | 1.0 ou posterior                                                                                                      |
| aiohttp     | 3.9 ou posterior                                                                                                      |
| Plataformas | Linux, macOS e Windows nas arquiteturas com wheels publicadas para cada versão do Python                              |

O pacote inclui wheels compiladas quando disponíveis e usa uma implementação em Python puro quando as extensões Cython não podem ser compiladas. PyArrow é compatível com Python 3.10 a 3.14. Python 3.14 requer PyArrow 22 ou posterior.

<div id="installation">
  ## Instalação
</div>

Instale o ClickHouse Connect do [PyPI](https://pypi.org/project/clickhouse-connect/) via pip:

```bash theme={null}
pip install clickhouse-connect
```

As integrações opcionais são instaladas via extras:

```bash theme={null}
pip install "clickhouse-connect[async]"      # Native asyncio client
pip install "clickhouse-connect[pandas]"     # Pandas
pip install "clickhouse-connect[arrow]"      # PyArrow
pip install "clickhouse-connect[polars]"     # Polars
pip install "clickhouse-connect[sqlalchemy]" # SQLAlchemy dialect
pip install "clickhouse-connect[alembic]"    # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]"       # Embedded chDB backend
pip install "clickhouse-connect[tzdata]"     # IANA time zones on minimal systems
```

O ClickHouse Connect também pode ser instalado a partir do código-fonte:

* Execute `git clone` do [repositório no GitHub](https://github.com/ClickHouse/clickhouse-connect).
* Acesse a raiz do projeto e execute `pip install .`. O sistema de compilação instala o Cython automaticamente para compilar as extensões C opcionais.

A versão instalada está disponível em `clickhouse_connect.__version__`.

<div id="support-policy">
  ## Política de suporte
</div>

Atualize para a versão mais recente do ClickHouse Connect antes de relatar um issue. Registre issues no [projeto do GitHub](https://github.com/ClickHouse/clickhouse-connect/issues). O ClickHouse Connect é direcionado aos [lançamentos do ClickHouse com suporte ativo](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) no momento de cada lançamento do driver. Em geral, ele também funciona com versões mais antigas do servidor, mas tipos de dados e recursos de protocolo mais recentes podem exigir um servidor mais novo.

<div id="basic-usage">
  ## Uso básico
</div>

<div id="gather-your-connection-details">
  ### Obtenha os detalhes da conexão
</div>

Para se conectar ao ClickHouse via HTTP(S), você precisa das seguintes informações:

| Parâmetro(s)              | Descrição                                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `HOST` and `PORT`         | Normalmente, a porta é 8443 ao usar TLS ou 8123 quando não se usa TLS.                                            |
| `DATABASE NAME`           | Por padrão, há um banco de dados chamado `default`; use o nome do banco de dados ao qual você deseja se conectar. |
| `USERNAME` and `PASSWORD` | Por padrão, o nome de usuário é `default`. Use o nome de usuário apropriado para o seu caso de uso.               |

Os detalhes do seu serviço do ClickHouse Cloud estão disponíveis no console do ClickHouse Cloud.
Selecione um serviço e clique em **Connect**:

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=119293dc89fd9bb8fa178d0bec957ecc" alt="botão Connect do serviço do ClickHouse Cloud" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
  </Frame>
</div>

Escolha **HTTPS**. Os detalhes de conexão são exibidos em um comando `curl` de exemplo.

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=16a5a08d3a2c44601d981b9ee5a75216" alt="detalhes de conexão HTTPS do ClickHouse Cloud" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
  </Frame>
</div>

Se você estiver usando ClickHouse autogerenciado, os detalhes de conexão são definidos pelo administrador do seu ClickHouse.

<div id="establish-a-connection">
  ### Estabeleça uma conexão
</div>

Há dois exemplos de como se conectar ao ClickHouse:

* Conectar-se a um servidor ClickHouse em localhost.
* Conectar-se a um serviço do ClickHouse Cloud.

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### Use uma instância do cliente ClickHouse Connect para se conectar a um servidor ClickHouse no localhost:
</div>

```python theme={null}
import clickhouse_connect

client = clickhouse_connect.get_client(
    host="localhost",
    username="default",
    password="password",
)
```

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-cloud-service">
  #### Use uma instância do cliente ClickHouse Connect para se conectar a um serviço do ClickHouse Cloud:
</div>

<Tip>
  Use os detalhes da conexão obtidos anteriormente. Os serviços do ClickHouse Cloud exigem TLS, então use a porta 8443.
</Tip>

```python theme={null}
import clickhouse_connect

client = clickhouse_connect.get_client(
    host="HOSTNAME.clickhouse.cloud",
    port=8443,
    username="default",
    password="your password",
)
```

<div id="interact-with-your-database">
  ### Interaja com o seu banco de dados
</div>

Para executar um comando do ClickHouse SQL, use o método `command` do client:

```python theme={null}
client.command(
    "CREATE TABLE new_table "
    "(key UInt32, value String, metric Float64) "
    "ENGINE MergeTree ORDER BY key"
)
```

Para inserir dados em lote, use o método `insert` do cliente com um array bidimensional de linhas e valores:

```python theme={null}
row1 = [1000, "String Value 1000", 5.233]
row2 = [2000, "String Value 2000", -107.04]
data = [row1, row2]
client.insert("new_table", data, column_names=["key", "value", "metric"])
```

Para consultar dados usando ClickHouse SQL, use o método `query` do cliente:

```python theme={null}
result = client.query("SELECT max(key), avg(metric) FROM new_table")
print(result.result_rows)
# Output: [(2000, -50.9035)]

client.close()
```

<div id="embedded-chdb-backend">
  ## Backend embutido do chDB
</div>

O backend experimental do chDB executa consultas do ClickHouse dentro do processo do Python, sem um servidor HTTP. Instale o extra `chdb` e, em seguida, selecione o backend com `interface="chdb"` ou uma DSN `chdb://`:

```python theme={null}
import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT number FROM numbers(3)")
    print(result.result_rows)
    # Output: [(0,), (1,), (2,)]
```

O banco de dados padrão fica em memória. Passe `path="/data/my_chdb"` ou use `dsn="chdb:///data/my_chdb"` para armazenamento persistente. O chDB permite apenas um caminho de engine por processo. Ele não oferece suporte ao cliente async nem a dados externos.