Configurações de capacidade do driver para o Databricks JDBC Driver (Simba)

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

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

Suporte a consultas ANSI SQL-92 em JDBC

Os drivers Legacy Spark JDBC aceitam consultas SQL no dialeto ANSI SQL-92 e traduzem-nas para Databricks SQL 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.

Catálogo e esquema padrão

Para especificar o catálogo e o esquema padrão, adicione ConnCatalog=<catalog-name>;ConnSchema=<schema-name> à URL de conexão JDBC.

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 ligação, inclua o parâmetro ssp_query_tags no URL de ligação JDBC.

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;ssp_query_tags=key1:value1,key2:value2

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, key1:value1,key2:value2.

Extrair resultados de consulta grandes no JDBC

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

Serialização de seta no JDBC

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

Cloud Fetch no JDBC

A versão 2.6.19 do driver JDBC suporta Cloud Fetch, uma funcionalidade que recolhe resultados de consultas através do armazenamento na cloud configurado na sua implementação do 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 JDBC (Simba) lançadas após dezembro 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 log

Para permitir o login no driver JDBC, 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 o Registo no Guia de Controladores JDBC do Databricks.