Connecteur Databricks SQL pour Python

Databricks SQL Connector pour Python est une bibliothèque Python qui vous permet d’utiliser du code Python pour exécuter des commandes SQL sur des entrepôts De calcul à usage unique Azure Databricks et Databricks SQL Warehouses. Le connecteur Databricks SQL pour Python est plus facile à configurer et à utiliser que des bibliothèques Python similaires telles que pyodbc. Cette bibliothèque est conforme à la norme PEP 249 – python Database API Specification v 2.0.

Importante

Databricks SQL Connector pour Python version 3.0.0 et ultérieure prend en charge l’exécution native des requêtes paramétrables, ce qui empêche l’injection SQL et peut améliorer les performances des requêtes. Les versions précédentes ont utilisé l’exécution paramétrable inline, ce qui n’est pas sûr de l’injection SQL et présente d’autres inconvénients. Pour plus d’informations, consultez Utilisation des paramètres natifs.

Databricks SQL Connector pour Python prend également en charge le dialecte SQLAlchemy pour Azure Databricks, mais il doit être installé pour utiliser ces fonctionnalités. Consultez Utiliser SQLAlchemy avec Azure Databricks.

Spécifications

• Machine de développement exécutant Python 3.8 et versions ultérieures.
• Databricks vous recommande d’utiliser des environnements virtuels Python, tels que ceux fournis par venv inclus avec Python. Les environnements virtuels vous permettent d’assurer que vous utilisez une combinaison des bonnes versions de Python et du connecteur Databricks SQL. La configuration et l’utilisation des environnements virtuels n’entrent pas dans le cadre de cet article. Pour plus d’informations, consultez la Création d’environnements virtuels.
• Un calcul à usage général ou un entrepôt SQL existant.

Bien démarrer

1. Installez databricks SQL Connector pour Python. PyArrow est une dépendance facultative du connecteur DATAbricks SQL pour Python et n’est pas installé par défaut dans la version 4.0.0 et versions ultérieures du connecteur. Si PyArrow n’est pas installé, les fonctionnalités telles que CloudFetch et d’autres fonctionnalités Apache Arrow ne sont pas disponibles, ce qui peut avoir un impact sur les performances des grands volumes de données.

   • Pour installer le connecteur lean, utilisez :

     pip install databricks-sql-connector
     

   • Pour installer le connecteur complet, y compris PyArrow, utilisez :

     pip install databricks-sql-connector[pyarrow]
     

2. Rassemblez les informations suivantes pour le calcul à usage entier ou l’entrepôt SQL que vous souhaitez utiliser :

   Calcul à usage général

   • Nom d’hôte du serveur du calcul à usage unique. Vous pouvez obtenir cette valeur à partir de la valeur du nom d’hôte du serveur dans l’onglet Options > avancées JDBC/ODBC pour votre calcul à usage unique.
   • Chemin HTTP du calcul à usage entier. Vous pouvez l’obtenir à partir de la valeur de chemin HTTP sous l’onglet Options > avancées JDBC/ODBC pour votre calcul à usage entier.

   Remarque

   Le connecteur SQL ne prend pas en charge la connexion à l'environnement de calcul des tâches.

   Entrepôt SQL

   • Nom d’hôte du serveur de l’entrepôt SQL. Vous pouvez l’obtenir à partir de la valeur Nom d'hôte du serveur sous l’onglet Détails de la connexion pour votre entrepôt SQL.
   • Chemin HTTP de l’entrepôt SQL. Vous pouvez l’obtenir à partir de la valeur Chemin HTTP sous l’onglet Détails de la connexion pour votre entrepôt SQL.

Authentification

Le connecteur Databricks SQL pour Python prend en charge les types d’authentification Azure Databricks suivants :

• Authentification par jeton d’accès personnel Databricks
• Authentification par jeton Microsoft Entra ID
• Authentification machine à machine (M2M) OAuth
• Authentification OAuth utilisateur à machine (U2M)

Le connecteur Databricks SQL pour Python ne prend pas encore en charge les types d’authentification Azure Databricks suivants :

• S’authentifier avec des identités managées Azure
• S’authentifier auprès des "service principals" Microsoft Entra
• S’authentifier auprès d’Azure CLI

Authentification par jeton d’accès personnel Databricks

Pour utiliser databricks SQL Connector pour Python avec l’authentification par jeton d’accès personnel Azure Databricks, vous devez d’abord créer un jeton d’accès personnel Azure Databricks. Pour ce faire, suivez les étapes décrites dans Créer des jetons d’accès personnels pour les utilisateurs de l’espace de travail.

Utilisez l’extrait de code suivant pour authentifier le connecteur SQL Databricks pour Python. Cet extrait suppose que vous avez défini les variables d’environnement suivantes :

• DATABRICKS_SERVER_HOSTNAMEdéfini sur la valeur du nom d’hôte du serveur pour votre calcul à usage unique ou votre entrepôt SQL.
• DATABRICKS_HTTP_PATH, défini sur la valeur HTTP Path (Chemin HTTP) de votre capacité de calcul polyvalente ou entrepôt SQL.
• DATABRICKS_TOKEN, défini sur le jeton d'accès personnel d'Azure Databricks.

Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Authentification OAuth machine à machine (M2M)

Les versions 2.7.0 et supérieures de Connecteur Databricks SQL pour Python supportent l’authentification OAuth machine à machine (M2M). Vous devez également installer le Kit de développement logiciel (SDK) Databricks pour Python 0.18.0 ou ultérieur (par exemple en exécutant pip install databricks-sdk ou python -m pip install databricks-sdk).

Pour utiliser le Connecteur Databricks SQL pour Python avec l’authentification OAuth machine à machine (M2M), vous devez effectuer les opérations suivantes :

1. Créez un principal de service Azure Databricks dans votre espace de travail Azure Databricks et créez un secret OAuth pour ce principal de service.

   Pour créer le principal de service et son secret OAuth, consultez Autoriser l’accès au principal de service à Azure Databricks avec OAuth. Notez la valeur UUID ou l’ID d’application du principal de service, ainsi que la valeur secrète du secret OAuth du principal de service.

2. Accordez à ce principal de service l’accès à votre capacité de calcul polyvalente ou à votre entrepôt.

   Pour accorder au principal de service l’accès à votre entrepôt ou calcul à usage unique, consultez Autorisations de calcul ou Gérer un entrepôt SQL.

Utilisez l’extrait de code suivant pour authentifier le connecteur SQL Databricks pour Python. Cet extrait suppose que vous avez défini les variables d’environnement suivantes :

• DATABRICKS_SERVER_HOSTNAME défini sur la valeur du nom d’hôte du serveur pour votre calcul à usage unique ou votre entrepôt SQL.
• DATABRICKS_HTTP_PATH, défini sur la valeur HTTP Path (Chemin HTTP) de votre capacité de calcul polyvalente ou entrepôt SQL.
• DATABRICKS_CLIENT_ID, assigné au principal de service avec la valeur UUID ou ID d’application.
• DATABRICKS_CLIENT_SECRET, défini sur la valeur secret pour le secret OAuth du principal de service.

Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation.

from databricks.sdk.core import Config, oauth_service_principal
from databricks import sql
import os

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

with sql.connect(server_hostname      = server_hostname,
                 http_path            = os.getenv("DATABRICKS_HTTP_PATH"),
                 credentials_provider = credential_provider) as connection:
# ...

Authentification par jeton Microsoft Entra ID

Pour utiliser le connecteur Databricks SQL pour Python avec l’authentification par jeton Microsoft Entra ID, vous devez fournir le connecteur Databricks SQL pour Python avec le jeton Microsoft Entra ID. Pour créer un jeton d’accès Microsoft Entra ID, effectuez ce qui suit :

• Vous pouvez utiliser l’interface utilisateur Azure CLI pour un utilisateur Azure Databricks. Consultez Obtenez manuellement les jetons Microsoft Entra ID.
• Pour un principal de service Microsoft Entra ID, consultez Obtenir des jetons pour les principaux de service. Pour créer un principal de service managé Microsoft Entra ID, consultez Principaux de service.

Les jetons Microsoft Entra ID ont une durée de vie par défaut d’environ une heure. Pour créer un jeton Microsoft Entra ID, répétez ce processus.

Utilisez l’extrait de code suivant pour authentifier le connecteur SQL Databricks pour Python. Cet extrait suppose que vous avez défini les variables d’environnement suivantes :

• Définissez DATABRICKS_SERVER_HOSTNAME la valeur du nom d’hôte du serveur pour votre calcul à usage unique ou votre entrepôt SQL.
• Définissez la DATABRICKS_HTTP_PATH valeur du chemin HTTP pour votre calcul à usage entier ou votre entrepôt SQL.
• Réglez DATABRICKS_TOKEN sur le jeton Microsoft Entra ID.

Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

Authentification OAuth utilisateur à machine (U2M)

Le connecteur Databricks SQL pour Python versions 2.7.0 et ultérieures prend en charge l'authentification OAuth utilisateur-à-machine (U2M). Vous devez également installer le Kit de développement logiciel (SDK) Databricks pour Python 0.19.0 ou ultérieur (par exemple en exécutant pip install databricks-sdk ou python -m pip install databricks-sdk).

Utilisez l’extrait de code suivant pour authentifier le connecteur SQL Databricks pour Python à l’aide de l’authentification U2M OAuth. L’authentification U2M OAuth utilise la connexion et le consentement humains en temps réel pour authentifier le compte d’utilisateur Azure Databricks cible. Cet extrait suppose que vous avez défini les variables d’environnement suivantes :

• Définissez DATABRICKS_SERVER_HOSTNAME la valeur du nom d’hôte du serveur pour votre calcul à usage unique ou votre entrepôt SQL.
• Définissez la DATABRICKS_HTTP_PATH valeur du chemin HTTP pour votre calcul à usage entier ou votre entrepôt SQL.

Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 auth_type       = "databricks-oauth") as connection:
# ...

Exemples

Les exemples de code suivants montrent comment utiliser databricks SQL Connector pour Python pour interroger et insérer des données, des métadonnées de requête, gérer des curseurs et des connexions, gérer des fichiers dans le catalogue Unity et configurer la journalisation.

Remarque

Les exemples de code suivants montrent comment utiliser un jeton d’accès personnel Azure Databricks pour l’authentification. Pour utiliser un autre type d’authentification, consultez Authentification.

Ces exemples de code récupèrent leurs valeurs de variables de connexion server_hostname, http_pathet access_token à partir de ces variables d’environnement :

• DATABRICKS_SERVER_HOSTNAME, qui représente la valeur Nom d’hôte du serveur issue des exigences.
• DATABRICKS_HTTP_PATH, qui représente la valeur Chemin HTTP issue des exigences.
• DATABRICKS_TOKEN, qui représente votre jeton d’accès conformément aux exigences.

Définir l’agent utilisateur

L’exemple de code suivant montre comment définir l’application User-Agent product_name pour le suivi de l’utilisation.

from databricks import sql
import os

with sql.connect(server_hostname   = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path         = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token      = os.getenv("DATABRICKS_TOKEN"),
                 user_agent_entry = "product_name") as connection:
  with connection.cursor() as cursor:
    cursor.execute("SELECT 1 + 1")
    result = cursor.fetchall()

    for row in result:
      print(row)

Interroger des données

L’exemple de code suivant montre comment appeler le connecteur Databricks SQL pour Python afin d’exécuter une commande SQL de base sur le calcul à usage unique ou l’entrepôt SQL. Cette commande renvoie les deux premières lignes de la table trips dans le schéma samples du catalogue nyctaxi.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
    result = cursor.fetchall()

    for row in result:
      print(row)

Balises de requête

Importante

Cette fonctionnalité est disponible en préversion privée . Pour demander l’accès, contactez l’équipe de votre compte.

L’exemple suivant montre comment attacher des balises clé-valeur à vos requêtes SQL à des fins de suivi et d’analytique. Les balises de requête s’affichent dans la system.query.history table.

from databricks import sql
import os

with sql.connect(
    server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
    http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
    access_token    = os.getenv("DATABRICKS_TOKEN"),
    session_configuration = {
        'query_tags': 'team:engineering,dashboard:abc123,env:prod'
    }
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
        result = cursor.fetchall()
        # Query is now tagged and trackable in system.query.history
        for row in result:
            print(row)

Insertion des données

L’exemple suivant montre comment insérer de petites quantités de données (milliers de lignes) :

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("CREATE TABLE IF NOT EXISTS squares (x int, x_squared int)")

    squares = [(i, i * i) for i in range(100)]

    cursor.executemany("INSERT INTO squares VALUES (?, ?)", squares)

    cursor.execute("SELECT * FROM squares LIMIT ?", [10])

    result = cursor.fetchall()

    for row in result:
      print(row)

Pour de grandes quantités de données, vous devez d’abord charger les données dans le stockage cloud, puis exécuter la commande COPY INTO.

Métadonnées de requête

Il existe des méthodes dédiées pour récupérer des métadonnées. L’exemple suivant récupère des métadonnées sur les colonnes dans un exemple de table :

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.columns(schema_name="default", table_name="squares")
    print(cursor.fetchall())

Gérer les curseurs et les connexions

C’est une meilleure pratique que de fermer les connexions et les curseurs qui ne sont plus utilisés. Cela libère des ressources sur le calcul polyvalent et les entrepôts SQL de Databricks Azure.

Vous pouvez utiliser un gestionnaire de contexte (syntaxe with utilisée dans les exemples précédents) pour gérer les ressources, ou appeler explicitement close :

from databricks import sql
import os

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")
print(cursor.fetchall())

cursor.close()
connection.close()

Gérer les fichiers dans les volumes de catalogue Unity

Le connecteur Databricks SQL vous permet d’écrire des fichiers locaux dans des volumes Unity Catalog, de télécharger des fichiers depuis des volumes et de supprimer des fichiers dans des volumes, comme illustré dans l’exemple suivant :

from databricks import sql
import os

# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allowed_local_path argument to the path to the
# local folder that contains the files to be written or downloaded.
# For deleting files in volumes, you must also specify the
# staging_allowed_local_path argument, but its value is ignored,
# so in that case its value can be set for example to an empty string.
with sql.connect(server_hostname            = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path                  = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token               = os.getenv("DATABRICKS_TOKEN"),
                 staging_allowed_local_path = "/tmp/") as connection:

  with connection.cursor() as cursor:

    # Write a local file to the specified path in a volume.
    # Specify OVERWRITE to overwrite any existing file in that path.
    cursor.execute(
      "PUT '/tmp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE"
    )

    # Download a file from the specified path in a volume.
    cursor.execute(
      "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'"
    )

    # Delete a file from the specified path in a volume.
    cursor.execute(
      "REMOVE '/Volumes/main/default/my-volume/my-data.csv'"
    )

Configuration de la journalisation

Databricks SQL Connector utilise le module de journalisation standard de Python. L’exemple suivant configure le niveau de journalisation et génère un journal de débogage :

from databricks import sql
import os, logging

logging.getLogger("databricks.sql").setLevel(logging.DEBUG)
logging.basicConfig(filename = "results.log",
                    level    = logging.DEBUG)

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")

result = cursor.fetchall()

for row in result:
   logging.debug(row)

cursor.close()
connection.close()

En cours de test

Pour tester votre code, utilisez des infrastructures de test Python comme pytest. Pour tester votre code dans des conditions simulées sans appeler de points de terminaison d’API REST Azure Databricks ni changer l’état de vos comptes ou espaces de travail Azure Databricks, vous pouvez utiliser des bibliothèques de simulation Python comme unittest.mock.

Par exemple, étant donné le fichier suivant nommé helpers.py contenant une fonction qui utilise un get_connection_personal_access_token jeton d’accès personnel Azure Databricks pour retourner une connexion à un espace de travail Azure Databricks et une select_nyctaxi_trips fonction qui utilise la connexion pour obtenir le nombre spécifié de lignes de données à partir de la table dans le tripssamples schéma du nyctaxi catalogue :

# helpers.py

from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor

def get_connection_personal_access_token(
  server_hostname: str,
  http_path: str,
  access_token: str
) -> Connection:
  return sql.connect(
    server_hostname = server_hostname,
    http_path = http_path,
    access_token = access_token
  )

def select_nyctaxi_trips(
  connection: Connection,
  num_rows: int
) -> List[Row]:
  cursor: Cursor = connection.cursor()
  cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [num_rows])
  result: List[Row] = cursor.fetchall()
  return result

Et étant donné le fichier suivant nommé main.py qui appelle les fonctions get_connection_personal_access_token et select_nyctaxi_trips :

# main.py

from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips

connection: Connection = get_connection_personal_access_token(
  server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
  http_path = os.getenv("DATABRICKS_HTTP_PATH"),
  access_token = os.getenv("DATABRICKS_TOKEN")
)

rows: List[Row] = select_nyctaxi_trips(
  connection = connection,
  num_rows = 2
)

for row in rows:
  print(row)

Le fichier suivant nommé test_helpers.py teste si la fonction select_nyctaxi_trips retourne la réponse attendue. Au lieu de créer une connexion réelle à l’espace de travail cible, ce test simule un objet Connection. Le test simule également des données qui sont conformes au schéma et aux valeurs qui se trouvent dans les données réelles. Le test retourne les données fictives via la connexion simulée, puis vérifie si l’une des valeurs des lignes de données simulées correspond à la valeur attendue.

# test_helpers.py

import pytest
from databricks.sql.client import Connection, List, Row
from datetime import datetime
from helpers import select_nyctaxi_trips
from unittest.mock import create_autospec

@pytest.fixture
def mock_data() -> List[Row]:
  return [
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 14, 16, 52, 13),
      tpep_dropoff_datetime = datetime(2016, 2, 14, 17, 16, 4),
      trip_distance = 4.94,
      fare_amount = 19.0,
      pickup_zip = 10282,
      dropoff_zip = 10171
    ),
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 4, 18, 44, 19),
      tpep_dropoff_datetime = datetime(2016, 2, 4, 18, 46),
      trip_distance = 0.28,
      fare_amount = 3.5,
      pickup_zip = 10110,
      dropoff_zip = 10110
    )
  ]

def test_select_nyctaxi_trips(mock_data: List[Row]):
  # Create a mock Connection.
  mock_connection = create_autospec(Connection)

  # Set the mock Connection's cursor().fetchall() to the mock data.
  mock_connection.cursor().fetchall.return_value = mock_data

  # Call the real function with the mock Connection.
  response: List[Row] = select_nyctaxi_trips(
    connection = mock_connection,
    num_rows = 2)

  # Check the value of one of the mocked data row's columns.
  assert response[1].fare_amount == 3.5

Étant donné que la fonction select_nyctaxi_trips contient une instruction SELECT et ne modifie donc pas l’état de la table trips, la simulation n’est pas absolument nécessaire dans cet exemple. Toutefois, la simulation vous permet d’exécuter rapidement vos tests sans attendre qu’une connexion réelle soit établie avec l’espace de travail. En outre, la simulation vous permet d’exécuter des tests simulés plusieurs fois pour les fonctions susceptibles de modifier l’état d’une table, comme INSERT INTO, UPDATEet DELETE FROM.

Informations de référence sur l'API

Cette section contient des informations de référence sur l’API pour le databricks-sql-connector package. Consultez databricks-sql-connector dans l’index de package Python (PyPI).

Module

Le databricks.sql module du databricks-sql-connector package contient la méthode permettant d’initialiser une connexion à un entrepôt SQL.

méthode de connexion

Initialise une connexion à un entrepôt SQL. Renvoie un objet Connection.

Paramètre	Type	Descriptif
server_hostname	str	Obligatoire. Nom d’hôte du serveur pour le calcul à usage entier ou l’entrepôt SQL, par exemple adb-1234567890123456.7.azuredatabricks.net. Pour obtenir le nom d’hôte du serveur, consultez les instructions de prise en main.
http_path	str	Obligatoire. Chemin HTTP du calcul à usage unique ou de l’entrepôt SQL, par exemple sql/protocolv1/o/1234567890123456/1234-567890-test123 pour un calcul à usage unique ou /sql/1.0/warehouses/a1b234c567d8e9fa pour un entrepôt SQL. Pour obtenir le chemin HTTP, consultez les instructions de prise en main.
access_token, auth_type, , credentials_provider, password, username	str	Informations sur les paramètres d’authentification Azure Databricks. Pour plus d’informations, consultez Authentification.
session_configuration	dict[str, Any]	Dictionnaire de paramètres de configuration de session Spark. La définition d’une configuration équivaut à l’utilisation de la commande SQL SET key=val. Exécutez la commande SQL SET -v pour obtenir la liste complète des configurations disponibles. La valeur par défaut est None. Exemple : {"spark.sql.variable.substitute": True}
http_headers	List[Tuple[str, str]]]	Optional. Paires supplémentaires (clé, valeur) à définir dans les en-têtes HTTP sur chaque demande RPC effectuée par le client. L’utilisation classique ne définit aucun en-tête HTTP supplémentaire. La valeur par défaut est None.
catalog	str	Optional. Catalogue initial à utiliser pour la connexion. Par défaut, None (au cas où le catalogue par défaut, généralement hive_metastore, sera utilisé).
schema	str	Optional. Schéma initial à utiliser pour la connexion. Par défaut : None (auquel cas le schéma default par défaut est utilisé). Depuis la version 2.0
use_cloud_fetch	bool	Optional. Indique s’il faut envoyer des demandes d’extraction directement au magasin d’objets cloud pour télécharger des blocs de données. La valeur par défaut est True. Définir sur False pour envoyer des requêtes de récupération directement à Azure Databricks. Si use_cloud_fetch est défini sur True, mais que l’accès réseau est bloqué, les demandes d’extraction échouent. Depuis la version 2.8
user_agent_entry	str	Optional. Entrée User-Agent à inclure dans l’en-tête de requête HTTP pour le suivi de l’utilisation. La valeur par défaut est PyDatabricksSqlConnector.

Connection classe

Représente une connexion au calcul ou à un entrepôt SQL.

Méthodes

La Connection classe fournit les méthodes suivantes.

Méthode	Descriptif
close	Ferme la connexion à la base de données et libère toutes les ressources associées sur le serveur. Tous les appels supplémentaires à cette connexion lèveront une Error. Aucun paramètre. Aucune valeur renvoyée.
cursor	Retourne un nouvel objet Cursor qui active la traversée sur les enregistrements d’une base de données. Aucun paramètre.

Cursor classe

Représente un mécanisme permettant de parcourir les enregistrements de données.

Pour créer un Cursor objet, appelez la cursor méthode de la classe Connection.

Attributs

Les attributs Cursor sélectionnés incluent ce qui suit :

Caractéristique	Descriptif
arraysize	Utilisée avec la méthode fetchmany, spécifie la taille de la mémoire tampon interne, ce qui correspond également au nombre de lignes récupérées du serveur en une seule fois. La valeur par défaut est 10000. Pour affiner les résultats (dans lesquels chaque ligne ne contient pas beaucoup de données), vous devez augmenter cette valeur afin d’améliorer les performances. Accès en lecture/écriture.
description	Contient un list Python de tuple objets. Chacun de ces tuple objets contient 7 valeurs, les 2 premiers éléments de chaque objet tuple contenant des informations décrivant une seule colonne de résultats comme suit : name: nom de la colonne. type_code: chaîne représentant le type de la colonne. Par exemple, une colonne d’entiers aura un code de type int. Les 5 éléments restants de chaque objet tuple de 7 éléments ne sont pas implémentés et leurs valeurs ne sont pas définies. Elles sont généralement retournées sous la forme de 4 None valeurs suivies d’une seule True valeur. Accès en lecture seule

Méthodes

Les méthodes Cursor sélectionnées incluent ce qui suit :

Méthode	Descriptif
cancel	Interrompt l’exécution d’une requête ou d’une commande de base de données démarrée par le curseur. Pour libérer les ressources associées sur le serveur, appelez la close méthode après l’appel de la cancel méthode. Aucun paramètre. Aucune valeur renvoyée.
close	Ferme le curseur et libère les ressources associées sur le serveur. La fermeture d’un curseur déjà fermé peut générer une erreur. Aucun paramètre. Aucune valeur renvoyée.
execute	Prépare puis exécute une requête ou une commande de base de données. Paramètres : operation:Obligatoire. Requête ou commande à préparer, puis exécuter. Type : str Exemple sans paramètre parameters : cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2') Exemple avec le paramètre à l’aide de paramètres positionnels natifs : parameters parameters : facultatif. Séquence de paramètres à utiliser avec le paramètre operation. Par défaut, il s’agit de None. Entrez : dictionary Aucune valeur renvoyée.
executemany	Prépare puis exécute une requête ou une commande de base de données en utilisant toutes les séquences de paramètres dans l’argument seq_of_parameters. Seul le jeu de résultats final est conservé. Paramètres : operation:Obligatoire. Requête ou commande à préparer, puis exécuter. Entrez : str seq_of_parameters:Obligatoire. Séquence de nombreux jeux de valeurs de paramètres à utiliser avec le operation paramètre. Type : list de dict Aucune valeur renvoyée.
catalogs	Exécutez une requête de métadonnées à propos des catalogues. Les résultats réels doivent ensuite être extraits à l’aide des commandes fetchmany ou fetchall. Les champs importants dans le jeu de résultats sont les suivants : Nom du champ : TABLE_CAT. Nom du catalogue. Entrez : str Aucun paramètre. Aucune valeur renvoyée. Depuis la version 1.0
schemas	Exécutez une requête de métadonnées à propos des schémas. Les résultats réels doivent ensuite être extraits à l’aide des commandes fetchmany ou fetchall. Les champs importants dans le jeu de résultats sont les suivants : Nom du champ : TABLE_SCHEM. Nom du schéma. Entrez : str Nom du champ : TABLE_CATALOG. Catalogue auquel le schéma appartient. Entrez : str Paramètres : catalog_name : facultatif. Nom du catalogue à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str schema_name : facultatif. Nom du schéma à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str Aucune valeur renvoyée. Depuis la version 1.0
tables	Exécutez une requête de métadonnées sur des tables et affichages. Les résultats réels doivent ensuite être extraits à l’aide des commandes fetchmany ou fetchall. Les champs importants dans le jeu de résultats sont les suivants : Nom du champ : TABLE_CAT. Catalogue auquel la table appartient. Entrez : str Nom du champ : TABLE_SCHEM. Schéma auquel la table appartient. Entrez : str Nom du champ : TABLE_NAME. Nom de la table. Entrez : str Nom du champ : TABLE_TYPE. Le type de relation, par exemple VIEW ou TABLE (s’applique à Databricks SQL 10.4 LTS et aux versions ultérieures, ainsi qu’à Databricks SQL. Les versions antérieures de Databricks Runtime retournent une chaîne vide). Entrez : str Paramètres : catalog_name : facultatif. Nom du catalogue à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str schema_name : facultatif. Nom du schéma à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str table_name : facultatif. Nom de la table à propos de laquelle récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str table_types : facultatif. Une liste de types de tables à faire correspondre, par exemple TABLE ou VIEW. Entrez : List[str] Aucune valeur renvoyée. Depuis la version 1.0
columns	Exécutez une requête de métadonnées à propos des colonnes. Les résultats réels doivent ensuite être extraits à l’aide des commandes fetchmany ou fetchall. Les champs importants dans le jeu de résultats sont les suivants : Nom du champ : TABLE_CAT. Catalogue auquel la colonne appartient. Entrez : str Nom du champ : TABLE_SCHEM. Schéma auquel la colonne appartient. Entrez : str Nom du champ : TABLE_NAME. Nom de la table à laquelle la colonne appartient. Entrez : str Nom du champ : COLUMN_NAME. Nom de la colonne. Entrez : str Paramètres : catalog_name : facultatif. Nom du catalogue à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str schema_name : facultatif. Nom du schéma à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str table_name : facultatif. Nom de la table à propos de laquelle récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str column_name : facultatif. Nom de la colonne à propos de laquelle récupérer des informations. Le caractère % est interprété comme un caractère générique. Entrez : str Aucune valeur renvoyée. Depuis la version 1.0
fetchall	Obtient toutes les lignes (ou les lignes restantes) d’une requête. Aucun paramètre. Retourne toutes les lignes (ou toutes les autres) de la requête sous la forme d’un Python list d’objets Row . Génère une Error si l’appel précédent à la méthode execute n’a retourné aucune données ou aucun appel execute n’a encore été effectué.
fetchmany	Obtient les lignes suivantes d’une requête. Paramètres : size : facultatif. Nombre de lignes suivantes à récupérer. S’il n’est pas spécifié, la valeur de l’attribut arraysize est utilisée. Entrez : int. Exemple : cursor.fetchmany(10) Retourne jusqu’à size (ou l’attribut arraysize si size n’est pas spécifié) des lignes suivantes d’une requête en tant qu’élément Python list d’objets Row. S’il reste moins de size lignes à extraire, toutes les lignes restantes sont retournées. Génère une Error si l’appel précédent à la méthode execute n’a retourné aucune données ou aucun appel execute n’a encore été effectué.
fetchone	Obtient la ligne suivante du jeu de données. Aucun paramètre. Retourne la ligne suivante du jeu de données sous la forme d’une séquence unique en tant qu’objet Python tuple , ou retourne None s’il n’y a plus de données disponibles. Génère une Error si l’appel précédent à la méthode execute n’a retourné aucune données ou aucun appel execute n’a encore été effectué.
fetchall_arrow	Obtient toutes les lignes (ou celles restantes) d’une requête, sous la forme d’un objet Table. Les requêtes retournant de très grandes quantités de données doivent utiliser fetchmany_arrow à la place pour réduire la consommation de mémoire. Aucun paramètre. Retourne toutes les lignes (ou celles restantes) de la requête sous la forme d’une table PyArrow. Génère une Error si l’appel précédent à la méthode execute n’a retourné aucune données ou aucun appel execute n’a encore été effectué. Depuis la version 2.0
fetchmany_arrow	Obtient les lignes suivantes d’une requête sous forme d'objet Table PyArrow. Paramètres : size : facultatif. Nombre de lignes suivantes à récupérer. S’il n’est pas spécifié, la valeur de l’attribut arraysize est utilisée. Entrez : int. Exemple : cursor.fetchmany_arrow(10) Retourne jusqu'à la valeur de l'argument size (ou de l'attribut arraysize si size n'est pas spécifié) pour les prochaines lignes d'une requête, sous forme d'un objet PyArrow Python Table. Génère une Error si l’appel précédent à la méthode execute n’a retourné aucune données ou aucun appel execute n’a encore été effectué. Depuis la version 2.0

Row classe

La classe de ligne est une structure de données de type tuple qui représente une ligne de résultat individuelle dans un résultat de requête SQL. Si la ligne contient une colonne du nom "my_column", vous pouvez accéder au champ "my_column" de row via row.my_column. Vous pouvez également utiliser des indices numériques pour accéder aux champs, par exemple row[0]. Si le nom de la colonne n’est pas autorisé en tant que nom de méthode d’attribut (par exemple, s’il commence par un chiffre), vous pouvez accéder au champ en tant que row["1_my_column"].

Depuis la version 1.0

Les méthodes Row sélectionnées incluent ce qui suit :

Méthodes

Méthode	Descriptif
asDict	Retourne une représentation sous forme de dictionnaire de la ligne, indexée par noms de champ. S’il existe des noms de champ en double, l’un des champs en double (mais un seul) sera retourné dans le dictionnaire. Le champ en double qui est retourné n’est pas défini.

Conversions des types

Le tableau suivant mappe des types de données Apache Spark SQL aux types de données Python équivalents.

Type de données Apache Spark SQL	Type de données Python
array	numpy.ndarray
bigint	int
binary	bytearray
boolean	bool
date	datetime.date
decimal	decimal.Decimal
double	float
int	int
map	str
null	NoneType
smallint	int
string	str
struct	str
timestamp	datetime.datetime
tinyint	int

Collecte de données de télémétrie

Databricks SQL Connector pour Python collecte des données de télémétrie pour aider Azure Databricks à améliorer la fiabilité et à résoudre les problèmes. La télémétrie est activée par défaut et collecte les données opérationnelles suivantes :

• Détails de l’environnement client, tels que la version du pilote, le runtime Python et le système d’exploitation
• Configurations de connexion de pilote (à l’exclusion des informations d’identification personnelle)
• Mesures de latence des opérations
• Formats de résultats d’exécution, tels que JSON inline ou Apache Arrow
• Types d’opérations, tels que l’exécution des requêtes, les requêtes de métadonnées ou les opérations de volume
• Données de classification des erreurs
• Nombre de nouvelles tentatives

Importante

Azure Databricks ne collecte pas de contenu de requête, de résultats de requête ou d’informations d’identification personnelle (PII) via la télémétrie.

Pour désactiver la collecte de données de télémétrie, définissez le paramètre enable_telemetry sur 0 lors de la création d'une connexion.

Dépannage

tokenAuthWrapperInvalidAccessToken: Invalid access token, message

Problème : lorsque vous exécutez votre code, vous voyez un message similaire à Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Cause possible : la valeur transmise à access_token n’est pas un jeton d’accès personnel Azure Databricks valide.

Correctif recommandé : vérifiez que la valeur transmise à access_token est correcte, puis réessayez.

gaierror(8, 'nodename nor servname provided, or not known'), message

Problème : lorsque vous exécutez votre code, vous voyez un message similaire à Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Cause possible : la valeur transmise à server_hostname n’est pas le nom d’hôte correct.

Correctif recommandé : vérifiez que la valeur transmise à server_hostname est correcte, puis réessayez.

Pour plus d’informations sur la recherche du nom d’hôte du serveur, consultez Obtenir les détails de connexion pour une ressource de calcul Azure Databricks.

IpAclError, message

Problème : lorsque vous exécutez votre code, le message Error during request to server: IpAclValidation s’affiche quand vous tentez d’utiliser le connecteur sur un notebook Azure Databricks.

Cause possible : vous avez peut-être activé une liste d’adresses IP autorisées pour l’espace de travail Azure Databricks. Avec la liste verte d’adresses IP, les connexions de clusters Spark au plan de contrôle ne sont pas autorisées par défaut.

Correctif recommandé : demandez à votre administrateur d’ajouter le sous-réseau du plan de calcul à la liste verte d’adresses IP.

Ressources supplémentaires

Pour plus d'informations, consultez les pages suivantes :

• Le référentiel Connecteur Databricks SQL pour Python sur GitHub
• Types de données
• Types intégrés (pour bool, bytearray, float, int et str) sur le site web Python
• dateheure (pour datetime.date et datatime.datetime) sur le site web Python
• décimal (pour decimal.Decimal) sur le site web de Python
• Constantes intégrées (pour NoneType) sur le site web Python