Propriedades de conexão suportadas

Este artigo descreve as propriedades de conexão compatíveis com o driverDatabricks JDBC (OSS).

Propriedades de autenticação e proxy

As seguintes propriedades de conexão são compatíveis com o Databricks JDBC Driver (OSS). As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
AsyncExecPollInterval	200	O tempo em milissegundos entre cada pesquisa para o status de execução da consulta assíncrona. Assíncrono refere-se ao fato de que a chamada RPC usada para executar uma consulta no Spark é assíncrona. Isso não significa que haja suporte para operações assíncronas de JDBC.
Auth_Flow	0	O fluxo de autenticação OAuth2 para a conexão do driver. Essa propriedade é necessária se AuthMech for 11.
Auth_JWT_Key_File	null	O caminho para o arquivo key privado (formato PEM) para autenticação JWT.
Auth_JWT_Alg	RS256	O algoritmo para autenticação privada key JWT. Os algoritmos suportados são: RSA: RS256, RS384, RS512, PS256, PS384, PS512 e EC: ES256, ES384, ES512
Auth_JWT_Key_Passphrase	null	A frase secreta para descriptografar um site privado criptografado key.
Auth_KID	null	O identificador de chave (KID) necessário para a autenticação JWT. Isso é obrigatório ao usar o key JWT privado.
AuthMech	Obrigatório	O mecanismo de autenticação, em que 3 especifica que o mecanismo é um Databricks tokens de acesso pessoal e 11 especifica que o mecanismo é OAuth 2.0 tokens. Propriedades adicionais são necessárias para cada mecanismo. Consulte Autenticar o driver.
CFProxyAuth	0	Se definido como 1, o driver usa o usuário e a senha de autenticação proxy, representados por CFProxyUID e CFProxyPwd.
CFProxyHost	null	Uma cadeia de caracteres que representa o nome do host proxy a ser usado quando UseCFProxy também é definido como 1.
CFProxyPort	null	Um inteiro que representa o número da porta proxy a ser usada quando UseCFProxy também está definido como 1.
CFProxyUID	null	Uma cadeia de caracteres que representa o nome de usuário a ser usado para autenticação de proxy quando CFProxyAuth e UseCFProxy também são definidos como 1.
CFProxyPwd	null	Uma cadeia de caracteres que representa a senha a ser usada para autenticação de proxy quando CFProxyAuth e UseCFProxy também são definidos como 1.
ConnCatalog ou catalog	SPARK	O nome do catálogo default a ser usado.
ConnSchema ou schema	default	O nome do esquema default a ser usado. Isso pode ser especificado substituindo <schema> na URL pelo nome do esquema a ser usado ou definindo a propriedade ConnSchema com o nome do esquema a ser usado.
GoogleServiceAccount	null	Permite a autenticação usando um serviço do Google account.
GoogleCredentialsFile	null	O caminho para o arquivo JSON key para a autenticação do serviço Google account.
EnableOIDCDiscovery	1	Se definido como 1, o URL de descoberta do OpenID Connect será usado.
OIDCDiscoveryEndpoint	null	O URL de descoberta do OpenID Connect para recuperar a configuração do OIDC.
Auth_RefreshToken	null	Os tokens OAuth2 refresh usados para recuperar novos tokens de acesso.
OAuth2ConnAuthAuthorizeEndpoint	null	O URL do endpoint de autorização usado em um fluxo OAuth2.
OAuth2ConnAuthTokenEndpoint	null	Os tokens endpoint URL para o fluxo OAuth2.
ProxyAuth	0	Se definido como 1, o driver usa o usuário e a senha de autenticação proxy, representados por ProxyUID e ProxyPwd.
ProxyHost	null	Uma cadeia de caracteres que representa o nome do host proxy a ser usado quando UseProxy também é definido como 1.
ProxyPort	null	Um inteiro que representa o número da porta proxy a ser usada quando UseProxy também está definido como 1.
ProxyPwd	null	Uma cadeia de caracteres que representa a senha a ser usada para autenticação de proxy quando ProxyAuth e UseProxy também são definidos como 1.
ProxyUID	null	Uma cadeia de caracteres que representa o nome de usuário a ser usado para autenticação de proxy quando ProxyAuth e UseProxy também são definidos como 1.
SSL	1	Se o conector se comunica com o servidor Spark por meio de um soquete habilitado para SSL.
UseProxy	0	Se definido como 1, o driver usa as configurações de proxy fornecidas (por exemplo: ProxyAuth, ProxyHost, ProxyPort, ProxyPwd e ProxyUID).
UseSystemProxy	0	Se definido como 1, o driver usa as configurações de proxy que foram definidas no nível do sistema. Se alguma propriedade adicional do proxy for definida no URL da conexão, essas propriedades adicionais do proxy substituirão as que foram definidas no nível do sistema.
UseCFProxy	0	Se definido como 1, o driver usa as configurações do proxy de busca na nuvem, se elas forem fornecidas, caso contrário, use o proxy normal.
UseJWTAssertion	false	Habilita a autenticação privada key JWT para casos de uso M2M em que a autenticação secreta do cliente é restrita.
UserAgentEntry	browser	A entrada User-Agent a ser incluída na solicitação HTTP. Esse valor está no seguinte formato: [ProductName]/[ProductVersion] [Comment]
UseThriftClient	1	Se o driver JDBC deve usar o cliente Thrift ou as APIs Statement Execution.

Propriedades de configuração do SQL

As seguintes propriedades de configuração do SQL são compatíveis com o Databricks JDBC Driver (OSS). Eles também são descritos em Parâmetros de configuração. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
ansi_mode	TRUE	Se o comportamento ANSI SQL estrito deve ser ativado para determinadas funções e regras de conversão.
enable_photon	TRUE	Se o mecanismo de consulta vetorizada do Photon deve ser ativado.
legacy_time_parser_policy	EXCEPTION	Os métodos usados para analisar e formatar datas e carimbos de data/hora. Os valores válidos são EXCEPTION, LEGACY e CORRECTED.
max_file_partition_bytes	128m	O número máximo de bytes a serem compactados em uma única partição ao ler de fontes baseadas em arquivos. A configuração pode ser qualquer número inteiro positivo e, opcionalmente, incluir uma medida como b (bytes), k ou kb (1024 bytes).
read_only_external_metastore	false	Controla se um metastore externo é tratado como somente para leitura.
statement_timeout	172800	Define um tempo limite de instrução SQL entre 0 e 172800 segundos.
timezone	UTC	Defina o fuso horário local. IDs de região no formato area/city, como America/Los_Angeles ou deslocamentos de zona no formato (+|-) HH, (+|-) HH ou (+|-) HH:mm, por exemplo, -08, + 01:00 ou - 13:33:33. Além disso, UTC é suportado como um alias para + 00:00
use_cached_result	true	Se o Databricks SQL armazena em cache e reutiliza os resultados sempre que possível.

Propriedades de registro

As seguintes propriedades de registro são compatíveis com o Databricks JDBC Driver (OSS). As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
LogLevel	OFF	O nível de registro, que é um valor de 0 a 6: 0: Desative todos os registros. 1: Ativar o registro em log no nível FATAL, que logs eventos de erro muito graves que levarão o conector a abortar. 2: Habilite o registro em log no nível ERROR, que logs eventos de erro que ainda podem permitir que o conector continue em execução. 3: Ative o registro no nível WARNING (aviso), que logs eventos que podem resultar em erro se não forem tomadas medidas. 4: Habilite o registro no nível INFO, que logs informações gerais que descrevem o progresso do conector. 5: Ative o registro no nível DEBUG, que logs informações detalhadas que são úteis para a depuração do conector. 6: Habilite o registro no nível TRACE, que logs toda a atividade do conector. Use essa propriedade para ativar ou desativar o registro em log no conector e para especificar a quantidade de detalhes incluídos nos arquivos de log.
LogPath	Para determinar o caminho default para logs, o driver usa o valor definido para essas propriedades do sistema, nesta ordem de prioridade: user.dir java.io.tmpdir o diretório atual, em outras palavras .	O caminho completo para a pasta em que o conector salva os arquivos log quando o registro em log está ativado, como uma cadeia de caracteres. Para garantir que o URL de conexão seja compatível com todos os aplicativos JDBC, escape as barras invertidas (\) no caminho do arquivo digitando outra barra invertida. Se o valor LogPath for inválido, o conector enviará as informações dos registros para a transmissão de saída padrão (System.out).
LogFileSize	Sem máximo	O tamanho máximo permitido do arquivo log, especificado em MB
LogFileCount	Sem máximo	O número máximo de arquivos permitidos no site log

Ativar e configurar o registro

O driver JDBC é compatível com as estruturas Simple Logging Facade for Java (SLF4J) e java.util.logging (JUL). O driver usa a estrutura de registro JUL por default.

Para ativar e configurar o registro em log do driver JDBC:

1. Ative a estrutura de registro que você deseja usar:

   • Para o registro em log do SLF4J, defina a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER e forneça a implementação de ligação do SLF4J (compatível com o SLF4J versão 2.0.13 e acima) e o arquivo de configuração correspondente no classpath.
   • Para o registro de JUL, defina a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Este é o site default.

2. Defina a propriedade LogLevel nas cadeias de conexão para o nível desejado de informações a serem incluídas nos arquivos log.

3. Defina a propriedade LogPath nas cadeias de conexão como o caminho completo para a pasta onde o senhor deseja salvar os arquivos log.

   Por exemplo, o URL de conexão a seguir habilita o nível de registro 6 e salva os arquivos log no diretório C pasta:

   jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp

4. Reinicie o aplicativo JDBC e reconecte-se ao servidor para aplicar as configurações.

Outras propriedades do recurso

As propriedades a seguir ativam o recurso no driverDatabricks JDBC (OSS). As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
EnableComplexDatatypeSupport	0	Se definido como 1, será ativado o suporte a tipos de dados complexos (ARRAYs, STRUCTs, MAPs) como objetos nativos do site Java em vez de strings.
EnableTelemetry	0	Se definido como 1, a telemetria é ativada. Consulte Telemetria.
VolumeOperationAllowedLocalPaths	``	A lista separada por vírgulas de caminhos locais permitidos para downloads e upload de arquivos do UC Volume Ingestion. Os caminhos também incluem subdiretórios. Consulte gerenciar arquivos usando volumes.

gerenciar arquivos usando volumes

Databricks oferece recursos de ingestão em massa (upload/download/remove) usando volumes Unity Catalog, permitindo que os usuários transfiram conjuntos de dados de e para arquivos locais, como arquivos CSV. Consulte O que são volumes do Unity Catalog? Para ativar as operações de volume do Unity Catalog, defina a propriedade de conexão VolumeOperationAllowedLocalPaths como uma lista separada por vírgulas de caminhos locais permitidos para as operações de volume.

O Unity Catalog deve estar ativado para usar esse recurso. Funcionalidade semelhante está disponível usando a interface do usuário do Databricks. Consulte Fazer upload de arquivos para um volume do Unity Catalog.

O comando de ingestão Unity Catalog são declarações SQL. Os exemplos abaixo demonstram as operações PUT, GET e REMOVE.

Fazer upload de um arquivo local

Para upload um arquivo local /tmp/test.csv em um caminho de volume Unity Catalog como /Volumes/main/default/e2etests/file1.csv, use as operações PUT:

Text

  PUT '/tmp/test.csv' INTO '/Volumes/main/default/e2etests/file1.csv' OVERWRITE

baixar um arquivo

Para download um arquivo do caminho /Volumes/main/default/e2etests/file1.csv do volume Unity Catalog em um arquivo local /tmp/test.csv, use as operações GET:

Text

  GET '/Volumes/main/default/e2etests/file1.csv' TO '/tmp/test.csv'

Excluir um arquivo

Para excluir um arquivo com um caminho de volume Unity Catalog /Volumes/main/default/e2etests/file1.csv, use as operações REMOVE:

Text

  REMOVE '/Volumes/main/default/e2etests/file1.csv'

Telemetria

A telemetria permite que a Databricks simplifique a depuração e ofereça solução de problemas em tempo hábil por meio da coleta:

• Detalhes do ambiente do cliente (versão do driver, tempo de execução, detalhes do sistema operacional)
• Configurações de conexão JDBC (exclui quaisquer dados de PII)
• operações medições de latência
• Formato do resultado da execução (JSON em linha, Arrow, etc.)
• tipos de operações (consulta de execução, consulta de metadados, operações de volume)
• Dados de classificação de erros
• Contagens de novas tentativas

nota

Databricks mantém padrões rígidos de privacidade, garantindo a não coleta de conteúdo de consultas, resultados ou informações de identificação pessoal (PII).