Configurações de capacidade do driver para o driver JDBC do Databricks (Simba)
Esta página se aplica ao driver JDBC Simba (legado), versões anteriores à versão 3. Databricks recomenda fortemente a migração para o driver JDBC Databricks para conectividade JDBC . Inclui melhorias como suporte para a visualização de métricas Unity Catalog , transações que abrangem várias instruções SQL , procedimentos armazenados, recuperação mais rápida de grandes volumes de resultados e telemetria integrada do cliente.
Esta página descreve como configurar as definições de capacidade especiais e avançadas do driver JDBC da Databricks.
O driver JDBC da Databricks fornece as seguintes configurações especiais e avançadas de recursos do driver.
Suporte a consultas ANSI SQL-92 em JDBC
Os drivers JDBC 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.
Catálogo e esquema padrão
Para especificar o catálogo e esquema padrão, adicione ConnCatalog=<catalog-name>;ConnSchema=<schema-name> na URL de conexão JDBC.
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 no URL da sua conexão JDBC:
jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;ssp_query_tags=key1:value1,key2:value2
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, key1:value1,key2:value2.
Extrair grandes resultados de consultas em JDBC
Para obter o melhor desempenho ao extrair resultados de consultas extensas, utilize a versão mais recente do driver JDBC, que incorpora as seguintes otimizações.
Serialização de setas em JDBC
JDBC O driver versão 2.6.16 e o acima oferecem suporte a um formato otimizado de serialização de resultados de consulta que usa Apache Arrow.
Cloud Fetch em JDBC
O driver JDBC versão 2.6.19 e superior suporta o Cloud Fetch, uma funcionalidade que busca resultados de consultas através do armazenamento cloud configurado na sua implementação Databricks .
Quando você executa uma query, o Databricks armazena os resultados no cloud storage do seu workspace como arquivos serializados em Arrow de até 20 MB. Após a execução da query, o driver envia solicitações de busca e o Databricks retorna URLs assinadas para os arquivos de resultado. O Driver usa então essas URLs para download 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 usar filtragem de IP de bucket, o filtro precisará 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 precisará ter um nível de acesso ou uma regra de entrada que permita solicitações da máquina cliente.
Para desativar o Cloud Fetch, defina EnableQueryResultDownload=0 na configuração da 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 está disponível nas versões do driver JDBC (Simba) lançadas após dezembro de 2025.
Se os downloads estiverem lentos ou travados, os URLs assinados poderão expirar antes que o driver termine de baixar todos os arquivos de resultados. 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 JDBC, 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 o log no guia Databricks JDBC Driver.