Configuración de la funcionalidad del controlador para el controlador JDBC de Databricks (Simba)

Nota:

Esta página se aplica a las versiones del controlador JDBC (heredado) debajo de la versión 3. Para el controlador JDBC de Databricks, versión 3 y posteriores, consulte Databricks JDBC Driver.

En esta página se describe cómo configurar opciones de funcionalidad de controlador especiales y avanzadas para el controlador JDBC de Databricks.

El controlador JDBC de Databricks proporciona la siguiente configuración de funcionalidad de controlador especial y avanzada.

Compatibilidad con consultas SQL-92 de ANSI en JDBC

Los controladores JDBC de Spark heredados aceptan consultas SQL en el dialecto ANSI SQL-92 y los traducen a Databricks SQL antes de enviarlos al servidor.

Si la aplicación genera Databricks SQL directamente o usa la sintaxis no ANSI SQL-92 específica de Azure Databricks, establezca UseNativeQuery=1 en la configuración de conexión. Esta configuración pasa las consultas SQL textualmente a Azure Databricks sin traducción.

Catálogo y esquema predeterminados

Para especificar el catálogo y el esquema predeterminados, agregue ConnCatalog=<catalog-name>;ConnSchema=<schema-name> a la dirección URL de conexión JDBC.

Etiquetas de consulta para el seguimiento

Importante

** Esta característica está disponible en versión preliminar privada. Para solicitar acceso, póngase en contacto con el equipo de su cuenta.

Adjunte etiquetas clave-valor a las consultas SQL con fines de seguimiento y análisis. Las etiquetas de consulta aparecen en la system.query.history tabla para la identificación y el análisis de consultas.

Para agregar etiquetas de consulta a la conexión, incluya el parámetro ssp_query_tags en la URL de conexión JDBC.

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

Defina etiquetas de consulta como pares clave-valor separados por comas, donde cada clave y valor están separados por dos puntos. Por ejemplo: key1:value1,key2:value2.

Extracción de resultados de consultas grandes en JDBC

Para lograr el mejor rendimiento al extraer resultados de consultas grandes, use la última versión del controlador JDBC, que incluye las siguientes optimizaciones.

Serialización de Arrow en JDBC

La versión 2.6.16 del controlador JDBC y versiones posteriores admiten un formato de serialización de resultados de consulta optimizado que usa Apache Arrow.

Cloud Fetch en JDBC

La versión 2.6.19 del controlador JDBC y versiones posteriores admite Cloud Fetch, una funcionalidad que captura los resultados de las consultas a través del almacenamiento en la nube configurado en la implementación de Azure Databricks.

Al ejecutar una consulta, Azure Databricks almacena los resultados en el almacenamiento en la nube del área de trabajo como archivos serializados con flecha de hasta 20 MB. Una vez completada la consulta, el controlador envía solicitudes de captura y Azure Databricks devuelve direcciones URL de firma de acceso compartido (SAS) a los archivos de resultados. A continuación, el controlador usa estas direcciones URL para descargar los resultados directamente desde Azure almacenamiento.

Cloud Fetch solo se aplica a los resultados de la consulta de más de 1 MB. El controlador recupera resultados más pequeños directamente de Azure Databricks.

Azure Databricks recolección automática de elementos no utilizados recopila archivos acumulados marcandolos para su eliminación después de 24 horas y quitándolos permanentemente 24 horas más tarde.

Requisitos previos de red

Si la red es privada, debe configurar las siguientes opciones para que Cloud Fetch funcione:

• Permitir *.blob.core.windows.net y *.store.core.windows.net en el entorno de red.
• Agregue las descargas y revocaciones de certificados necesarias a la lista de permitidos.
• Si la compatibilidad con firewall está habilitada en la cuenta de almacenamiento del área de trabajo de Azure Databricks, configure una puerta de enlace de datos de red virtual o puerta de enlace de datos local permitir el acceso privado a la cuenta de almacenamiento.

Para deshabilitar Cloud Fetch, establezca EnableQueryResultDownload=0 en la configuración de conexión.

Diagnóstico de descargas lentas

Establézcalo LogLevel en 4 (INFO) y LogPath en la ruta de acceso completa de una carpeta de registro para ver las métricas de velocidad de descarga de Cloud Fetch. El controlador registra la velocidad de descarga por fragmento, por lo que los conjuntos de resultados grandes generan varias líneas de registro. El controlador también registra una advertencia cuando la velocidad cae por debajo de aproximadamente 1 MB/s. Esta característica está disponible en las versiones del controlador JDBC (Simba) publicadas después de diciembre de 2025.

Si las descargas son lentas o se detiene, los tokens de SAS pueden expirar antes de que el controlador termine de descargar todos los archivos de resultados. Compruebe si hay limitación de ancho de banda o congestión de red entre el cliente y Azure Blob Storage.

Habilitar registro

Para habilitar el registro en el controlador JDBC, establezca la LogLevel propiedad en un valor entre 1 (solo eventos graves) y 6 (toda la actividad del controlador). Establezca la LogPath propiedad en la ruta de acceso completa de la carpeta donde desea guardar los archivos de registro.

Para obtener más información, consulte Configuración del registro en la Guía del controlador JDBC de Databricks.