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

Esta página descreve como configurar definições especiais e avançadas de capacidade de driver para o Databricks ODBC Driver.

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

Definir o esquema inicial no ODBC

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

Tags de consulta para acompanhamento

Anexe etiquetas-chave-valor às suas consultas SQL para fins de rastreamento e análise. As tags de consulta aparecem na tabela system.query.history para identificação e análise.

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

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

Suporte a consultas ANSI SQL-92 em ODBC

Os drivers ODBC do Spark Legacy aceitam consultas SQL no dialeto ANSI SQL-92 e traduzem-nas para SQLs Databricks antes de as enviar para o servidor.

Se a sua aplicação gerar SQL Databricks diretamente ou usar sintaxe SQL-92 não ANSI específica para Azure Databricks, defina UseNativeQuery=1 na configuração da sua ligação. Esta configuração passa consultas SQL literalmente para o Azure Databricks sem tradução.

Extrair resultados de consulta grandes no ODBC

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

Serialização de seta no ODBC

O driver ODBC versão 2.6.15 e superior suporta um formato de serialização de resultados de consulta otimizado que usa a Seta Apache.

Cloud Fetch em ODBC

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

Quando executa uma consulta, o Azure Databricks armazena os resultados no armazenamento na cloud do seu espaço de trabalho como ficheiros serializados Arrow de até 20 MB. Após a conclusão da consulta, o driver envia pedidos de busca e Azure Databricks devolve URLs assinatura de acesso partilhada (SAS) aos ficheiros de resultados. O driver utiliza então estas URLs para descarregar os resultados diretamente do armazenamento do Azure.

Cloud Fetch aplica-se apenas a resultados de consulta superiores a 1 MB. O driver recupera resultados mais pequenos diretamente do Azure Databricks.

O Azure Databricks recolhe automaticamente os ficheiros acumulados, marcando-os para eliminação após 24 horas e removendo-os permanentemente 24 horas depois.

Pré-requisitos de rede

Se a sua rede for privada, deve configurar as seguintes definições para que o Cloud Fetch funcione:

• Permita *.blob.core.windows.net e *.store.core.windows.net esteja no seu ambiente de rede.
• Adicione os downloads e revogações de certificados necessários à sua lista de autorizações.
• Se o suporte a firewall estiver ativado na sua conta de armazenamento Azure Databricks workspace, configure um gateway de dados virtual de rede ou um gateway de dados on-premises data para permitir acesso privado à conta de armazenamento.

Para desativar o Cloud Fetch, defina EnableQueryResultDownload=0 a configuração da sua ligação.

Diagnosticar downloads lentos

Defina LogLevel para 4 (INFO) e LogPath para o caminho completo de uma pasta de registo para ver as métricas de velocidade de download do Cloud Fetch. Os registos do driver transmitem a velocidade de download por chunk, por isso conjuntos de resultados grandes geram múltiplas linhas logarítmicas. O condutor também regista um aviso quando a velocidade cai abaixo de aproximadamente 1 MB/s. Esta funcionalidade está disponível nas versões do driver ODBC lançadas após novembro de 2025.

Se os downloads forem lentos ou parados, os tokens SAS podem expirar antes do driver terminar de descarregar todos os ficheiros de resultados. Verifique se há limitação de largura de banda ou congestionamento de rede entre o cliente e o Armazenamento de Blobs do Azure.

Ativar registo

Para permitir o login no driver ODBC, defina a LogLevel propriedade para um valor entre 1 (apenas eventos graves) e 6 (toda a atividade do driver). Define a LogPath propriedade para o caminho completo da pasta onde queres guardar os ficheiros de registo.

Para mais informações, consulte Configurar Opções de Registo numa Máquina Não Windows no Guia de Controladores ODBC Databricks.