> ## 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. > Documentação do driver ODBC do ClickHouse # Driver ODBC 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](/pt-BR/concepts/features/interfaces/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](https://github.com/ClickHouse/clickhouse-odbc). 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](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](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. ```powershell theme={null} $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](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 ](#sql-compatibility-settings) 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 ```plaintext theme={null} Driver={ClickHouse ODBC Driver (Unicode)};Url=http://localhost:8123/;Username=default ``` * Uma instância do ClickHouse Cloud. ```plaintext theme={null} 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](/pt-BR/integrations/connectors/data-visualization/powerbi-and-clickhouse).
## 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](/pt-BR/reference/settings/session-settings/cast#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: ```sql theme={null} SELECT sum(CAST(value, 'Int32')) FROM values ``` Por padrão, quando a coluna `value` aceita valores nulos, esta consulta falhará com a mensagem: ```plaintext theme={null} 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](/pt-BR/reference/settings/session-settings/prefer#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: ```sql theme={null} 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: ```sql theme={null} 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: ```sql theme={null} 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: ```plaintext theme={null} 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: ```plaintext theme={null} 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. ```sql theme={null} 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. ```sql theme={null} 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.