Uso avançado

Uso avançado com ClickHouse Connect

​

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.
settings	dict	None	Veja a descrição das configurações.
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)

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

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'  # ou CSV, ou CSVWithNamesAndTypes, ou 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:

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

Da mesma forma, você pode salvar dados em TabSeparated e em outros formatos. Consulte Formatos para dados de entrada e saída 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 e 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:

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.

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.

​

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). O comando SET do ClickHouse é usado para alterar as configurações no escopo de uma sessão de usuário.
• Acompanhar tabelas temporárias.

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

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:

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.