Configurações de capacidade do driver para o Databricks ODBC Driver

Esta página descreve como configurar as definições de capacidade especiais e avançadas do driver ODBC da Databricks.

O driver ODBC da Databricks fornece as seguintes configurações especiais e avançadas de recursos do driver.

Definir o esquema inicial no ODBC

O driver ODBC permite a você especificar o esquema definindo o Schema=<schema-name> como uma configuração de conexão. Isso é equivalente a executar USE <schema-name>.

tags de consulta para acompanhamento

Adicione tags key-valor às suas consultas SQL para fins de acompanhamento e análise. tags de consulta aparecem na tabela system.query.history para identificação e análise de consultas.

Para adicionar tags de consulta à sua conexão, inclua o parâmetro ssp_query_tags na configuração da sua conexão ODBC:

Defina tags de consulta como pares key-valor separados por vírgulas, onde cada key e valor são separados por dois pontos. Por exemplo, ssp_query_tags=team:engineering,env:prod.

Você também deve definir ApplySSPWithQueries=0 na configuração de conexão do seu driver ODBC.

Suporte a consultas ANSI SQL-92 em ODBC

Os drivers ODBC legados Spark aceitam consultas SQL no dialeto ANSI SQL-92 e as traduzem para Databricks SQL antes de enviá-las ao servidor.

Se o seu aplicativo gera Databricks SQL diretamente ou usa sintaxe SQL-92 não ANSI específica do Databricks, defina UseNativeQuery=1 na sua configuração de conexão. Essa configuração envia as consultas SQL literalmente para o Databricks, sem tradução.

Extrair grandes resultados de consultas em ODBC

Para obter o melhor desempenho ao extrair resultados de consultas extensas, utilize a versão mais recente do driver ODBC, que inclui as seguintes otimizações.

Serialização de setas no ODBC

ODBC A versão 2.6.15 do driver e o acima oferecem suporte a um formato otimizado de serialização de resultados de consulta que usa Apache Arrow.

Cloud Fetch em ODBC

O driver ODBC versão 2.6.17 e superior suporta o Cloud Fetch, uma funcionalidade que busca resultados de consultas através do armazenamento cloud configurado na sua implementação Databricks .

Ao executar uma query, o Databricks armazena os resultados no armazenamento em cloud do seu workspace como arquivos serializados em Arrow de até 20 MB. Depois que a query é concluída, o driver envia solicitações de busca e o Databricks retorna URLs assinadas para os arquivos de resultado. O Driver usa então estas URLs para download os resultados diretamente do Google Cloud Storage (GCS).

O recurso Cloud Fetch só se aplica a resultados de consulta maiores que 1 MB. O driver recupera resultados menores diretamente do Databricks.

O Databricks coleta automaticamente o lixo dos arquivos acumulados, marcando-os para exclusão após 24 horas e removendo-os permanentemente 24 horas depois.

Pré-requisitos de rede

O Cloud Fetch download arquivos de resultados diretamente do GCS. Se a máquina cliente não conseguir acessar o GCS, o Cloud Fetch falhará. Verifique o seguinte:

• As regras de proxy e firewall devem permitir o tráfego HTTPS para storage.googleapis.com.
• Se o bucket de armazenamento do seu workspace usa filtragem de IP de bucket, o filtro deve permitir os endereços IP da máquina cliente.
• Se o bucket de armazenamento do seu workspace estiver dentro de um perímetro do VPC Service Controls, o perímetro deverá ter um nível de acesso ou regra de entrada que permita solicitações da máquina cliente.

Para desabilitar o Cloud Fetch, defina EnableQueryResultDownload=0 na configuração da sua conexão.

Diagnosticar downloads lentos

Defina LogLevel para 4 (INFO) e LogPath para o caminho completo de uma pasta log para ver as métricas de velocidade download do Cloud Fetch. O driver logs a velocidade download por bloco, portanto, conjuntos de resultados grandes geram várias linhas log . O driver também logs um aviso quando a velocidade cai abaixo de aproximadamente 1 MB/s. Este recurso estará disponível nas versões do driver ODBC lançadas após novembro de 2025.

Se os downloads estiverem lentos ou parados, as URLs assinadas podem expirar antes que o driver termine de baixar todos os arquivos de resultado. Verifique se há limitação de largura de banda ou congestionamento de rede entre o cliente e o GCS.

Ativar registro

Para habilitar o registro no driver ODBC, defina a propriedade LogLevel para um valor entre 1 (somente eventos graves) e 6 (toda a atividade do driver). Defina a propriedade LogPath para o caminho completo da pasta onde você deseja salvar os arquivos de log.

Para obter mais informações, consulte "Configurando opções de registro em um computador que não seja Windows" no guia do driver ODBC Databricks .