Paramètres de capacité du Driver pour le Driver JDBC Databricks (Simba)
Cette page s'applique au Driver JDBC Simba (hérité), versions inférieures à la version 3. Databricks recommande vivement de migrer vers le Driver JDBC Databricks pour la connectivité JDBC. Il inclut des améliorations telles que la prise en charge des vues des indicateurs Unity Catalog, des transactions couvrant plusieurs instructions SQL, des procédures stockées, une récupération plus rapide des grands résultats et la télémétrie client intégrée.
Cette page décrit comment configurer les paramètres de capacités spéciales et avancées du Driver JDBC Databricks.
Le Driver JDBC Databricks fournit les paramètres de capacité de Driver spéciaux et avancés suivants.
Prise en charge des query ANSI SQL-92 en JDBC
Les pilotes JDBC Spark hérités acceptent les requêtes SQL dans le dialecte ANSI SQL-92 et les traduisent en Databricks SQL avant de les envoyer au serveur.
Si votre application génère directement du Databricks SQL ou utilise une syntaxe non ANSI SQL-92 spécifique à Databricks, définissez UseNativeQuery=1 dans votre configuration de connexion. Ce paramètre transmet les requêtes SQL telles quelles à Databricks sans traduction.
Catalogue et schéma par default
Pour spécifier le catalogue et le schéma default, ajoutez ConnCatalog=<catalog-name>;ConnSchema=<schema-name> à l'URL de connexion JDBC.
Balises de query pour le suivi
Attachez des tags clé-valeur à vos requêtes SQL à des fins de suivi et d'analytique. Les tags query apparaissent dans la table system.query.history pour l'identification et l'analyse des query.
Pour ajouter des query tags à votre connexion, incluez le parameter ssp_query_tags dans l'URL de votre connexion JDBC :
jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;ssp_query_tags=key1:value1,key2:value2
Définissez les tags de query sous forme de paires clé-valeur séparées par des virgules, où chaque clé et valeur est séparée par deux points. Par exemple, key1:value1,key2:value2.
Extraire des résultats de query volumineux dans JDBC
Pour obtenir les meilleures performances lors de l'extraction de grands résultats de query, utilisez la dernière version du driver JDBC, qui inclut les optimisations suivantes.
Sérialisation Arrow dans JDBC
La version 2.6.16 et supérieure du driver JDBC prend en charge un format de sérialisation des résultats de query optimisé qui utilise Apache Arrow.
Récupération Cloud en JDBC
Le Driver JDBC version 2.6.19 et supérieures prend en charge Cloud Fetch, une fonctionnalité qui récupère les résultats de query via le stockage cloud configuré dans votre déploiement Databricks.
Lorsque vous exécutez une query, Databricks stocke les résultats dans le stockage cloud de votre workspace sous forme de fichiers sérialisés Arrow pouvant atteindre 20 Mo. Une fois la query terminée, le driver envoie des requêtes de récupération et Databricks renvoie des URL signées vers les fichiers de résultat. Le driver utilise ensuite ces URL pour download les résultats directement depuis Google Cloud Storage (GCS).
Cloud Fetch ne s'applique qu'aux résultats de query supérieurs à 1 Mo. Le Driver récupère les résultats plus petits directement à partir de Databricks.
Databricks effectue automatiquement le nettoyage des fichiers accumulés en les marquant pour suppression après 24 heures et en les supprimant définitivement 24 heures plus tard.
Prérequis réseau
cloud Fetch download les fichiers de résultats directement à partir de GCS. Si la machine cliente ne peut pas atteindre GCS, Cloud Fetch échoue. Vérifiez les points suivants :
- Les règles de proxy et de pare-feu doivent autoriser le trafic HTTPS vers
storage.googleapis.com. - Si le bucket de stockage de votre workspace utilise le filtrage IP de bucket, le filtre doit autoriser les adresses IP de la machine cliente.
- Si le bucket de stockage de votre workspace se trouve à l’intérieur d’un périmètre VPC Service Controls, ce périmètre doit disposer d’un niveau d’accès ou d’une règle d’entrée autorisant les demandes provenant de la machine cliente.
Pour désactiver Cloud Fetch, définissez EnableQueryResultDownload=0 dans la configuration de votre connexion.
Diagnostiquer les download lents
Définissez LogLevel sur 4 (INFO) et LogPath sur le chemin complet d'un dossier de Logs pour voir les mesures de vitesse de download de Cloud Fetch. Le Driver enregistre également la vitesse de download par bloc, ainsi, les grands ensembles de résultats génèrent plusieurs lignes de Logs. Le Driver Logs également un avertissement lorsque la vitesse tombe en dessous d'environ 1 Mo/s. Cette fonctionnalité est disponible dans les versions du Driver JDBC (Simba) publiées après décembre 2025.
Si les download sont lents ou bloqués, les URL signées peuvent expirer avant que le Driver n'ait terminé le téléchargement de tous les fichiers de résultats. Vérifiez la présence de limitation de bande passante ou d'encombrement du réseau entre le client et GCS.
Activer la journalisation
Pour activer la journalisation dans le driver JDBC, définissez la propriété LogLevel sur une valeur entre 1 (événements graves uniquement) et 6 (toute l'activité du driver). Définissez la propriété LogPath sur le chemin complet du dossier où vous souhaitez enregistrer les Logs.
Pour plus d'informations, consultez Configuring Logging dans le Guide du Driver JDBC Databricks.