Driver ODBC

Documentação do driver ODBC do ClickHouse

O driver ODBC do ClickHouse oferece uma interface compatível com os padrões para conectar aplicações compatíveis com ODBC ao ClickHouse. Ele implementa a API ODBC e permite que aplicações, ferramentas de BI e ambientes de script executem consultas SQL, recuperem resultados e interajam com o ClickHouse por meio de mecanismos conhecidos.

O driver se comunica com o servidor ClickHouse usando o protocolo HTTP, que é o principal protocolo compatível com todas as implantações do ClickHouse. Isso permite que o driver opere de forma consistente em diversos ambientes, incluindo instalações locais, serviços gerenciados em nuvem e ambientes nos quais apenas o acesso baseado em HTTP está disponível.

O código-fonte do driver está disponível no repositório do ClickHouse-ODBC no GitHub.

Para garantir melhor compatibilidade, recomendamos fortemente atualizar seu servidor ClickHouse para a versão 24.11 ou posterior.

Este driver está em desenvolvimento ativo. Alguns recursos do ODBC talvez ainda não estejam totalmente implementados. A versão atual concentra-se em fornecer conectividade essencial e as principais funcionalidades do ODBC, com recursos adicionais planejados para lançamentos futuros.

Seu feedback é muito valioso e ajuda a orientar a priorização de novos recursos e melhorias. Se encontrar limitações, funcionalidades ausentes ou comportamentos inesperados, compartilhe suas observações ou solicitações de recursos por meio do rastreador de issues em https://github.com/ClickHouse/clickhouse-odbc/issues

​

Instalação no Windows

Você pode encontrar a versão mais recente do driver em https://github.com/ClickHouse/clickhouse-odbc/releases/latest. Nessa página, você pode baixar e executar o instalador MSI e seguir as etapas simples de instalação.

​

Teste

Você pode testar o driver executando este script simples do PowerShell. Copie o texto abaixo, defina a URL, o usuário e a senha e cole-o no prompt de comando do PowerShell. Após executar $reader.GetValue(0), a versão do servidor ClickHouse deverá ser exibida.

$url = "http://127.0.0.1:8123/"
$username = "default"
$password = ""
$conn = New-Object System.Data.Odbc.OdbcConnection("`
    Driver={ClickHouse ODBC Driver (Unicode)};`
    Url=$url;`
    Username=$username;`
    Password=$password")
$conn.Open()
$cmd = $conn.CreateCommand()
$cmd.CommandText = "select version()"
$reader = $cmd.ExecuteReader()
$reader.Read()
$reader.GetValue(0)
$reader.Close()
$conn.Close()

​

Parâmetros de configuração

Os parâmetros abaixo correspondem às configurações mais usadas para estabelecer uma conexão com o driver ODBC do ClickHouse. Eles abrangem opções essenciais de autenticação, comportamento da conexão e manipulação de dados. Uma lista completa dos parâmetros compatíveis está disponível na página do projeto no GitHub https://github.com/ClickHouse/clickhouse-odbc.

• Url: Especifica o endpoint HTTP(S) completo do servidor ClickHouse. Isso inclui o protocolo, host, porta e caminho opcional.
• Username: O nome de usuário usado para autenticação no servidor ClickHouse.
• Password: A senha associada ao nome de usuário especificado. Se não for fornecida, o driver se conecta sem autenticação por senha.
• Database: O banco de dados padrão a ser usado na conexão.
• Timeout: O tempo máximo (em segundos) que o driver aguarda uma resposta do servidor antes de cancelar a solicitação.
• ClientName: Um identificador personalizado enviado ao servidor ClickHouse como parte dos metadados do cliente. Útil para rastrear ou distinguir o tráfego de diferentes aplicações. Esse parâmetro fará parte do cabeçalho User-Agent nas solicitações HTTP geradas pelo driver.
• Compression: Habilita ou desabilita a compressão HTTP para os payloads de solicitações e respostas. Quando habilitada, ela pode reduzir o uso de largura de banda e melhorar o desempenho de grandes conjuntos de resultados.
• SqlCompatibilitySettings: Habilita configurações de consulta que fazem o ClickHouse se comportar mais como um banco de dados relacional tradicional. Isso é útil quando as consultas são geradas automaticamente por ferramentas de terceiros, por exemplo, o Power BI. Essas ferramentas geralmente não reconhecem determinados comportamentos específicos do ClickHouse e podem gerar consultas que resultam em erros ou resultados inesperados. Consulte Configurações do ClickHouse usadas pelo parâmetro de configuração SqlCompatibilitySettings para mais detalhes.

Veja alguns exemplos de strings de conexão completas passadas ao driver para estabelecer uma conexão.

• Um servidor ClickHouse instalado localmente em uma instância do WSL

Driver={ClickHouse ODBC Driver (Unicode)};Url=http://localhost:8123/;Username=default

• Uma instância do ClickHouse Cloud.

Driver={ClickHouse ODBC Driver (Unicode)};Url=https://you-instance-url.gcp.clickhouse.cloud:8443/;Username=default;Password=your-password

​

Integração com o Microsoft Power BI

Você pode usar o driver ODBC para conectar o Microsoft Power BI a um servidor ClickHouse. O Power BI oferece duas opções de conexão: o conector ODBC genérico e o conector ClickHouse, ambos incluídos nas instalações padrão do Power BI.

Ambos os conectores usam ODBC internamente, mas diferem em suas funcionalidades:

• Conector ClickHouse (recomendado) Usa ODBC internamente, mas oferece suporte ao modo DirectQuery. Nesse modo, o Power BI gera automaticamente consultas SQL e recupera apenas os dados necessários para cada visualização ou operação de filtragem.

• Conector ODBC Oferece suporte apenas ao modo Importar. O Power BI executa a consulta fornecida pelo usuário (ou seleciona a tabela inteira) e importa o conjunto completo de resultados para o Power BI. As atualizações subsequentes reimportam todo o conjunto de dados.

Escolha o conector de acordo com seu caso de uso. O DirectQuery é mais adequado para painéis interativos com grandes conjuntos de dados. Escolha o modo Importar quando precisar de cópias locais completas dos dados.

Para mais informações sobre a integração do Microsoft Power BI com o ClickHouse, consulte a página da documentação do ClickHouse sobre a integração com o Power BI.

​

Configurações de compatibilidade com SQL

O ClickHouse tem seu próprio dialeto SQL e, em alguns casos, comporta-se de maneira diferente de outros bancos de dados, como MS SQL Server, MySQL ou PostgreSQL. Muitas vezes, essas diferenças são vantajosas, pois introduzem uma sintaxe aprimorada que facilita o uso dos recursos do ClickHouse.

No entanto, o driver ODBC é frequentemente usado em ambientes nos quais as consultas são geradas por ferramentas de terceiros, como o Power BI, em vez de serem escritas pelos usuários. Essas consultas geralmente dependem de um subconjunto mínimo do SQL padrão. Nesses casos, os desvios do ClickHouse em relação ao SQL padrão podem não produzir o comportamento esperado e podem gerar resultados ou erros inesperados. O driver ODBC fornece um parâmetro de configuração adicional, SqlCompatibilitySettings, que habilita configurações específicas de consulta para aproximar o comportamento do ClickHouse ao SQL padrão.

​

Configurações do ClickHouse habilitadas pelo parâmetro de configuração SqlCompatibilitySettings

Esta seção descreve quais configurações o driver ODBC modifica e por quê.

cast_keep_nullable

Por padrão, o ClickHouse não permite converter tipos Nullable em tipos não anuláveis. No entanto, muitas ferramentas de BI não diferenciam tipos anuláveis de não anuláveis ao realizar conversões de tipos. Por isso, é comum ver consultas como a seguinte geradas por ferramentas de BI:

SELECT sum(CAST(value, 'Int32'))
FROM values

Por padrão, quando a coluna value aceita valores nulos, esta consulta falhará com a mensagem:

DB::Exception: Cannot convert NULL value to non-Nullable type: while executing 'FUNCTION CAST(__table1.value :: 2,
'Int32'_String :: 1) -> CAST(__table1.value, 'Int32'_String) Int32 : 0'. (CANNOT_INSERT_NULL_IN_ORDINARY_COLUMN)

Ativar cast_keep_nullable altera o comportamento de CAST para preservar a anulabilidade dos argumentos. Isso aproxima o comportamento do ClickHouse ao de outros bancos de dados e ao padrão SQL para esse tipo de conversão.

prefer_column_name_to_alias

O ClickHouse permite referenciar expressões na mesma lista SELECT pelos respectivos aliases. Por exemplo, esta consulta evita repetições e é mais fácil de escrever:

SELECT
    sum(value) AS S,
    count() AS C,
    S / C
FROM test

Esse recurso é amplamente utilizado, mas outros bancos de dados normalmente não resolvem aliases dessa forma na mesma lista SELECT, e essas consultas gerariam um erro. Os problemas são mais evidentes quando um alias tem o mesmo nome de uma coluna. Por exemplo:

SELECT
    sum(value) AS value,
    avg(value)
FROM test

Qual value a função avg(value) deve agregar? Por padrão, o ClickHouse dá preferência ao alias, transformando isso, na prática, em um agregado aninhado, o que não é o esperado pela maioria das ferramentas.

Por si só, isso raramente é um problema, mas algumas ferramentas de BI geram consultas com subconsultas que reutilizam aliases de coluna. Por exemplo, o Power BI geralmente gera consultas semelhantes à seguinte:

SELECT
    sum(C1) AS C1,
    count(C1) AS C2
FROM
(
    SELECT sum(value) AS C1
    FROM test
    GROUP BY group_index
) AS TBL

Referências a C1 podem gerar o seguinte erro:

Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function sum(C1) AS C1 is found
inside another aggregate function in query. (ILLEGAL_AGGREGATION)

Outros bancos de dados normalmente não resolvem aliases nesse mesmo nível e, em vez disso, tratam C1 como uma coluna da subconsulta. Para preservar um comportamento semelhante no ClickHouse e permitir que essas consultas sejam executadas sem erros, o driver ODBC habilita prefer_column_name_to_alias.

Na maioria dos casos, habilitar essas configurações não deve ser um problema. No entanto, usuários com a configuração readonly definida como 1 não podem alterar nenhuma configuração, nem mesmo em consultas SELECT. Para esses usuários, habilitar SqlCompatibilitySettings resultará em um erro. A seção a seguir explica como fazer esse parâmetro de configuração funcionar para usuários com acesso somente leitura.

​

Como usar configurações de compatibilidade com SQL para usuários somente leitura

Ao se conectar ao ClickHouse por meio do driver ODBC com o parâmetro SqlCompatibilitySettings habilitado, um usuário com a configuração readonly definida como 1 receberá um erro porque o driver tenta modificar as configurações da consulta:

Code: 164. DB::Exception: Cannot modify 'cast_keep_nullable' setting in readonly mode. (READONLY)
Code: 164. DB::Exception: Cannot modify 'prefer_column_name_to_alias' setting in readonly mode. (READONLY)

Isso acontece porque usuários no modo somente leitura não podem alterar configurações, mesmo em consultas SELECT individuais. Há várias maneiras de resolver esse problema.

Opção 1. Definir readonly como 2

Esta é a opção mais simples. Definir readonly como 2 permite alterar configurações e manter o usuário no modo somente leitura.

ALTER USER your_odbc_user MODIFY SETTING
    readonly = 2

Na maioria dos casos, definir readonly como 2 é a forma mais fácil e recomendada de resolver esse problema. Se isso não funcionar, use a segunda opção.

Opção 2. Alterar a configuração do usuário para corresponder às configurações definidas pelo driver ODBC.

Isso também é simples: atualize a configuração do usuário para que ela já corresponda ao que o driver ODBC tenta definir.

ALTER USER your_odbc_user MODIFY SETTING
    cast_keep_nullable = 1,
    prefer_column_name_to_alias = 1

Com essa alteração, o driver ODBC ainda pode tentar aplicar as configurações, mas, como os valores já correspondem, nenhuma alteração efetiva é realizada e o erro é evitado.

Essa opção também é simples, mas exige manutenção: versões mais recentes do driver podem alterar a lista de configurações ou adicionar novas configurações de compatibilidade. Se você definir essas configurações diretamente para seu usuário ODBC, talvez precise atualizá-las sempre que o driver ODBC começar a aplicar configurações adicionais.