> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Uso avançado com ClickHouse Connect
# Uso avançado
## API bruta
Para casos de uso que não exigem transformação entre dados do ClickHouse e tipos de dados e estruturas nativos ou de terceiros, o cliente ClickHouse Connect fornece métodos para usar diretamente a conexão com o ClickHouse.
### Método `raw_query` do cliente
O método `Client.raw_query` permite usar diretamente a interface HTTP de consulta do ClickHouse por meio da conexão do cliente. O valor retornado é um objeto `bytes` não processado. Ele oferece um wrapper conveniente com vinculação de parâmetros, tratamento de erros, novas tentativas e gerenciamento de configurações por meio de uma interface mínima:
| Parâmetro | Tipo | Padrão | Descrição |
| -------------- | ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | str | *Obrigatório* | Qualquer consulta válida do ClickHouse |
| parameters | dict or iterable | *None* | Veja a [descrição dos parâmetros](/pt-BR/integrations/language-clients/python/driver-api#parameters-argument). |
| settings | dict | *None* | Veja a [descrição das configurações](/pt-BR/integrations/language-clients/python/driver-api#settings-argument). |
| fmt | str | *None* | Formato de saída do ClickHouse para os bytes resultantes. (O ClickHouse usa TSV se não for especificado) |
| use\_database | bool | True | Usa o banco de dados atribuído ao cliente ClickHouse Connect no contexto da consulta |
| external\_data | ExternalData | *None* | Um objeto ExternalData contendo dados de arquivo ou dados binários para uso com a consulta. Veja [Consultas avançadas (Dados externos)](/pt-BR/integrations/language-clients/python/advanced-querying#external-data) |
Cabe a quem faz a chamada lidar com o objeto `bytes` resultante. Observe que `Client.query_arrow` é apenas um wrapper leve em torno desse método, usando o formato de saída `Arrow` do ClickHouse.
### Método `raw_stream` do cliente
O método `Client.raw_stream` tem a mesma API que o método `raw_query`, mas retorna um objeto `io.IOBase` que pode ser usado como gerador ou fluxo de objetos `bytes`. No momento, ele é utilizado pelo método `query_arrow_stream`.
### Método `raw_insert` do cliente
O método `Client.raw_insert` permite inserts diretos de objetos `bytes` ou geradores de objetos `bytes` usando a conexão do cliente. Como ele não faz nenhum processamento do payload de insert, oferece alto desempenho. O método fornece opções para especificar configurações e o formato de insert:
| Parâmetro | Tipo | Padrão | Descrição |
| ------------- | --------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
| table | str | *Obrigatório* | O nome simples da tabela ou o nome qualificado com o banco de dados |
| column\_names | Sequence\[str] | *None* | Nomes das colunas para o bloco de insert. Obrigatório se o parâmetro `fmt` não incluir os nomes |
| insert\_block | str, bytes, Generator\[bytes], BinaryIO | *Obrigatório* | Dados a serem usados no insert. Strings serão codificadas usando a codificação do cliente. |
| settings | dict | *None* | Consulte a [descrição das configurações](/pt-BR/integrations/language-clients/python/driver-api#settings-argument). |
| fmt | str | *None* | Formato de entrada do ClickHouse para os bytes de `insert_block`. (O ClickHouse usa TSV se não for especificado) |
É responsabilidade de quem chama garantir que o `insert_block` esteja no formato especificado e use o método de compressão especificado. O ClickHouse Connect usa esses inserts brutos para uploads de arquivos e tabelas PyArrow, delegando o parsing ao servidor ClickHouse.
## Salvando resultados de consultas em arquivos
Você pode transferir arquivos diretamente do ClickHouse para o sistema de arquivos local usando o método `raw_stream`. Por exemplo, se quiser salvar os resultados de uma consulta em um arquivo CSV, poderá usar o seguinte trecho 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'
fmt = 'CSVWithNames' # or CSV, or CSVWithNamesAndTypes, or TabSeparated, etc.
stream = client.raw_stream(query=query, fmt=fmt)
with open("output.csv", "wb") as f:
for chunk in stream:
f.write(chunk)
```
O código acima gera um arquivo `output.csv` com o seguinte conteúdo:
```csv theme={null}
"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"
```
Da mesma forma, você pode salvar dados em [TabSeparated](/pt-BR/reference/formats/TabSeparated/TabSeparated) e em outros formatos. Consulte [Formatos para dados de entrada e saída](/pt-BR/reference/formats/index) para ter uma visão geral de todas as opções de formato disponíveis.
## Casos de uso multithread, multiprocesso e assíncronos/orientados a eventos
O ClickHouse Connect funciona bem em aplicações multithread, multiprocesso e orientadas a loop de eventos/assíncronas. Todo o processamento de consultas e inserts ocorre em uma única thread, portanto as operações em geral são thread-safe. (O processamento paralelo de algumas operações em baixo nível é uma possível melhoria futura para superar a perda de desempenho de uma única thread, mas, mesmo nesse caso, a segurança entre threads será mantida.)
Como cada consulta ou insert executado mantém estado em seu próprio objeto `QueryContext` ou `InsertContext`, respectivamente, esses objetos auxiliares não são thread-safe e não devem ser compartilhados entre vários fluxos de processamento. Veja a discussão adicional sobre objetos de contexto nas seções [QueryContexts](/pt-BR/integrations/language-clients/python/advanced-querying#querycontexts) e [InsertContexts](/pt-BR/integrations/language-clients/python/advanced-inserting#insertcontexts).
Além disso, em uma aplicação que tenha duas ou mais consultas e/ou inserts "em andamento" ao mesmo tempo, há mais dois pontos a considerar. O primeiro é a "sessão" do ClickHouse associada à consulta/insert, e o segundo é o pool de conexões HTTP usado pelas instâncias do cliente ClickHouse Connect.
## Wrapper do AsyncClient
O ClickHouse Connect fornece um wrapper assíncrono para o `Client` padrão, possibilitando o uso do cliente em um ambiente `asyncio`.
Para obter uma instância de `AsyncClient`, você pode usar a função de fábrica `get_async_client`, que aceita os mesmos parâmetros do `get_client` padrão:
```python theme={null}
import asyncio
import clickhouse_connect
async def main():
client = await clickhouse_connect.get_async_client()
result = await client.query("SELECT name FROM system.databases LIMIT 1")
print(result.result_rows)
# Saída:
# [('INFORMATION_SCHEMA',)]
asyncio.run(main())
```
`AsyncClient` tem os mesmos métodos e os mesmos parâmetros do `Client` padrão, mas eles são corrotinas quando aplicável. Internamente, esses métodos do `Client` que realizam operações de E/S são encapsulados em uma chamada [run\_in\_executor](https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor).
O desempenho multithread aumentará ao usar o wrapper `AsyncClient`, pois as threads de execução e o GIL serão liberados enquanto se aguarda a conclusão das operações de E/S.
Observação: Diferentemente do `Client` comum, o `AsyncClient` força `autogenerate_session_id` a ser `False` por padrão.
Veja também: [exemplo run\_async](https://github.com/ClickHouse/clickhouse-connect/blob/main/examples/run_async.py).
## Gerenciando IDs de sessão do ClickHouse
Cada consulta do ClickHouse ocorre no contexto de uma "sessão" do ClickHouse. Atualmente, as sessões são usadas para duas finalidades:
* Associar configurações específicas do ClickHouse a várias consultas (consulte [configurações do usuário](/pt-BR/reference/settings/session-settings)). O comando `SET` do ClickHouse é usado para alterar as configurações no escopo de uma sessão de usuário.
* Acompanhar [tabelas temporárias.](/pt-BR/reference/statements/create/table#temporary-tables)
Por padrão, cada consulta executada com uma instância `Client` do ClickHouse Connect usa o ID de sessão desse cliente. Instruções `SET` e tabelas temporárias funcionam como esperado ao usar um único cliente. No entanto, o servidor do ClickHouse não permite consultas simultâneas na mesma sessão (o cliente gerará um `ProgrammingError` se isso for tentado). Para aplicações que executam consultas simultâneas, use um dos seguintes padrões:
1. Crie uma instância `Client` separada para cada thread/processo/manipulador de eventos que precise de isolamento de sessão. Isso preserva o estado da sessão de cada cliente (tabelas temporárias e valores de `SET`).
2. Use um `session_id` exclusivo para cada consulta por meio do argumento `settings` ao chamar `query`, `command` ou `insert`, se você não precisar de um estado de sessão compartilhado.
3. Desative as sessões em um cliente compartilhado definindo `autogenerate_session_id=False` antes de criar o cliente (ou passe isso diretamente para `get_client`).
```python theme={null}
from clickhouse_connect import common
import clickhouse_connect
common.set_setting('autogenerate_session_id', False) # Isso deve sempre ser definido antes de criar um cliente
client = clickhouse_connect.get_client(host='somehost.com', user='dbuser', password=1234)
```
Como alternativa, passe `autogenerate_session_id=False` diretamente para `get_client(...)`.
Nesse caso, o ClickHouse Connect não envia um `session_id`; o servidor não considera que requisições separadas pertençam à mesma sessão. Tabelas temporárias e configurações no nível da sessão não serão mantidas entre as requisições.
## Personalizando o pool de conexões HTTP
O ClickHouse Connect usa pools de conexões do `urllib3` para gerenciar a conexão HTTP subjacente com o servidor. Por padrão, todas as instâncias de cliente compartilham o mesmo pool de conexões, o que é suficiente para a maioria dos casos de uso. Esse pool padrão mantém até 8 conexões HTTP Keep Alive para cada servidor ClickHouse usado pela aplicação.
Para aplicações grandes e multithread, pode ser mais adequado usar pools de conexões separados. Pools de conexões personalizados podem ser fornecidos como o argumento nomeado `pool_mgr` para a função 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)
```
Como mostra o exemplo acima, os clientes podem compartilhar o mesmo gerenciador de pool, ou um gerenciador de pool separado pode ser criado para cada cliente. Para mais detalhes sobre as opções disponíveis ao criar um PoolManager, consulte a [documentação do `urllib3`](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#customizing-pool-behavior).