Connecteur Databricks SQL pour Python

Le connecteur Databricks SQL pour Python est une bibliothèque Python qui vous permet d’utiliser du code Python pour exécuter des commandes SQL sur des clusters Azure Databricks et des entrepôts Databricks SQL. 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.

Remarque

Le connecteur SQL Databricks pour Python inclut également un dialecte SQLAlchemy pour Azure Databricks. Consultez Utiliser SQLAlchemy avec Azure Databricks.

Spécifications

• Un ordinateur de développement exécutant Python >=3.8 et <=3.11.
• 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.
• Cluster ou entrepôt SQL existant.

Bien démarrer

• Installez la bibliothèque du connecteur Databricks SQL pour Python sur votre ordinateur de développement en exécutant pip install databricks-sql-connector ou python -m pip install databricks-sql-connector.

• Collectez les informations suivantes pour le cluster ou l’entrepôt SQL que vous souhaitez utiliser :

  Cluster

  • Nom d’hôte du serveur du cluster. Vous pouvez extraire celui-ci de la valeur Nom d'hôte du serveur sous l’onglet Options avancées > JDBC/ODBC pour votre cluster.
  • Chemin d’accès HTTP du cluster. Vous pouvez extraire celui-ci de la valeur Chemin d'accès HTTP sous l’onglet Options avancées > JDBC/ODBC pour votre cluster.

  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 OAuth machine à machine (M2M)
• Authentification utilisateur à machine (U2M) OAuth

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

• Authentification par identités managées Azure
• Authentification du principal de service MS Entra
• Authentification Azure CLI

Authentification par jeton d’accès personnel Databricks

Pour utiliser le connecteur Databricks SQL 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 comme suit :

1. Dans votre espace de travail Azure Databricks, cliquez sur votre nom d’utilisateur Azure Databricks dans la barre du haut, puis sélectionnez Paramètres dans la liste déroulante.
2. Cliquez sur Développeur.
3. À côté de Jetons d’accès, cliquez sur Gérer.
4. Cliquez sur Générer un nouveau jeton.
5. (Facultatif) Entrez un commentaire qui vous aide à identifier ce jeton à l’avenir et modifiez sa durée de vie par défaut (90 jours). Pour créer un jeton sans durée de vie (non recommandé), laissez vide la zone Durée de vie (en jours).
6. Cliquez sur Générer.
7. Copiez le jeton affiché dans un emplacement sécurisé, puis cliquez sur Terminé.

Remarque

Veillez à enregistrer le jeton copié dans un emplacement sécurisé. Ne partagez pas votre jeton copié avec d'autres. Si vous le perdez, vous ne pouvez pas régénérer exactement le même. Vous devez donc répéter cette procédure pour créer un jeton. Si vous perdez le jeton copié ou si vous pensez que le jeton a été compromis, Databricks vous recommande vivement de supprimer immédiatement ce jeton de votre espace de travail en cliquant sur l’icône de la corbeille (Révoquer) à côté du jeton de la page Jetons d’accès.

Si vous n'êtes pas en mesure de créer ou d'utiliser des jetons dans votre espace de travail, cela peut être dû au fait que votre administrateur d'espace de travail a désactivé les jetons ou ne vous a pas donné l'autorisation de créer ou d'utiliser des jetons. Consultez votre administrateur d'espace de travail ou les rubriques suivantes :

• Activer ou désactiver l'authentification par jeton d'accès personnel pour l'espace de travail
• Autorisations de jeton d'accès personnel

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 réglé sur la valeur Nom d'hôte de serveur de votre cluster ou entrepôt SQL.
• DATABRICKS_HTTP_PATH, réglé sur la valeur Chemin HTTP de votre cluster ou entrepôt SQL.
• DATABRICKS_TOKEN, réglé sur le jeton d’accès personnel 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 Authentifier l’accès à Azure Databricks avec un principal de service à l’aide d’OAuth (OAuth M2M). Notez la valeur de l’UUID ou de l’ID de l’application du principal de service, ainsi que la valeur du secret OAuth du principal de service.

2. Accordez à ce principal de service l’accès à votre cluster ou entrepôt.

   Pour accorder au principal de service l’accès à votre cluster ou entrepôt, 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 cluster ou votre entrepôt SQL.
• DATABRICKS_HTTP_PATH, réglé sur la valeur Chemin HTTP de votre cluster ou entrepôt SQL.
• DATABRICKS_CLIENT_ID, est fixé à la valeur de l’UUID ou de l’ID de l’application du principal de service.
• DATABRICKS_CLIENT_SECRET, définie sur la valeur Secret du 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 Obtenir des jetons Microsoft Entra ID pour les utilisateurs avec Azure CLI.
• Pour un principal de service Microsoft Entra ID, consultez Obtenir un jeton d’accès Microsoft Entra ID avec Azure CLI. Pour créer un principal de service géré par Microsoft Entra ID, consultez Gérer les 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 :

• Réglez DATABRICKS_SERVER_HOSTNAME sur la valeur Nom d'hôte de serveur de votre cluster ou entrepôt SQL.
• Réglez DATABRICKS_HTTP_PATH sur la valeur Chemin HTTP de votre cluster ou 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 utilisateur à machine (U2M) OAuth

Le connecteur Databricks SQL pour Python versions 2.7.0 et ultérieures prennent en charge l’authentification utilisateur à machine (U2M) OAuth. 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 :

• Réglez DATABRICKS_SERVER_HOSTNAME sur la valeur Nom d'hôte de serveur de votre cluster ou entrepôt SQL.
• Réglez DATABRICKS_HTTP_PATH sur la valeur Chemin HTTP de votre cluster ou 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 le connecteur Databricks SQL pour Python pour interroger et insérer des données, des métadonnées de requête, gérer des curseurs et des connexions, 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 plutôt d’autres types d’authentification Azure Databricks, consultez l’article 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 à partir des exigences.

Vous pouvez utiliser d’autres approches pour récupérer ces valeurs de variable de connexion. L’utilisation de variables d’environnement n’est qu’une seule approche parmi plusieurs.

• Données de requête
• Insérer des données
• Métadonnées de requête
• Gérer les curseurs et les connexions
• Gérer les fichiers dans les volumes de catalogue Unity
• Configurer la journalisation

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 un cluster ou un entrepôt SQL. Cette commande retourne les deux premières lignes de la table trips dans le schéma nyctaxi du catalogue samples.

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)

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)]
    values = ",".join([f"({x}, {y})" for (x, y) in squares])

    cursor.execute(f"INSERT INTO squares VALUES {values}")

    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 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 les clusters Azure Databricks et les entrepôts Databricks SQL.

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_allows_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_allows_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 '/temp/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

Le connecteur Databricks SQL utilise le module de journalisation standardde Python. Vous pouvez configurer le niveau de journalisation similaire à ce qui suit :

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()

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 get_connection_personal_access_token qui utilise un jeton d’accès personnel Azure Databricks pour renvoyer une connexion à un espace de travail Azure Databricks, et une fonction select_nyctaxi_trips qui utilise la connexion pour obtenir le nombre spécifié de lignes de données dans la table trips dans le schéma nyctaxi du catalogue samples :

# 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(f"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 renvoie les données simulées sur la connexion simulée, puis vérifie si 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

• Package
• Module
• Classes
• Connection, classe
• Cursor, classe
• Row, classe
• Conversions des types

Package

databricks-sql-connector

Utilisation : pip install databricks-sql-connector

Consultez aussi databricks-sql-connector dans l’index de package Python (PyPI).

Module

databricks.sql

Utilisation : from databricks import sql

Classes

Les classes sélectionnées incluent ce qui suit :

Classes
Connection Une session sur une ressource de calcul Azure Databricks.
Cursor Un mécanisme pour traverse des enregistrements de données.
Row Une ligne de données dans un résultat de requête SQL.

Classe Connection

Pour créer un objet Connection, appelez la méthode databricks.sql.connect avec les paramètres suivants :

Paramètres
server_hostname Entrez : str Nom d’hôte du serveur pour le cluster ou l’entrepôt SQL. Pour obtenir le nom d’hôte du serveur, consultez les instructions plus haut dans cet article. Ce paramètre est obligatoire. Exemple : adb-1234567890123456.7.azuredatabricks.net
http_path Entrez : str Chemin HTTP du cluster ou de l’entrepôt SQL. Pour obtenir le chemin d’accès HTTP, consultez les instructions plus haut dans cet article. Ce paramètre est obligatoire. Exemple : sql/protocolv1/o/1234567890123456/1234-567890-test123 pour un cluster. /sql/1.0/warehouses/a1b234c567d8e9fa pour un entrepôt SQL.
access_token, auth_type Entrez : str Informations sur les paramètres d’authentification Azure Databricks. Pour plus d’informations, consultez Authentification.
session_configuration Entrez : 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. Ce paramètre est facultatif. Exemple : {"spark.sql.variable.substitute": True}
http_headers Entrez : List[Tuple[str, str]]] 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. Ce paramètre est facultatif. Depuis la version 2.0
catalog Entrez : str Catalogue initial à utiliser pour la connexion. Par défaut : None (auquel cas le catalogue par défaut, généralement hive_metastore, est utilisé). Ce paramètre est facultatif. Depuis la version 2.0
schema Entrez : str Schéma initial à utiliser pour la connexion. Par défaut : None (auquel cas le schéma default par défaut est utilisé). Ce paramètre est facultatif. Depuis la version 2.0
use_cloud_fetch Entrez : bool True pour envoyer des demandes d’extraction directement au magasin d’objets cloud afin de télécharger des blocs de données. False (valeur par défaut) pour l’envoi de demandes d’extraction 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

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

Méthodes
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 objet Cursor qui permet de traverser les enregistrements d’une base de données. Aucun paramètres.

Classe Cursor

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

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

Attributs
arraysize Utilisés avec la méthode fetchmany, spécifie la taille de la mémoire tampon interne, qui est également le nombre de lignes réellement extraites une par une du serveur. 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. Ils seront généralement retournés comme 4 Valeurs None suivies d’une valeur True unique. Accès en lecture seule

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

Méthodes
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 méthode close après l’appel de la méthode cancel. 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. Aucune valeur renvoyée. Paramètres : operation Entrez : str Requête ou commande à préparer, puis exécuter. Ce paramètre est obligatoire. Exemple sans le paramètre parameters : cursor.execute( 'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2' ) Exemple avec le paramètre parameters : cursor.execute( 'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2', { 'pickup_zip': '10019' } ) parameters Type : dictionnaire Séquence de paramètres à utiliser avec le paramètre operation. Ce paramètre est facultatif. Par défaut, il s’agit de None.
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é. Aucune valeur renvoyée. Paramètres : operation Entrez : str Requête ou commande à préparer, puis exécuter. Ce paramètre est obligatoire. seq_of_parameters Type : list de dict Séquence de nombreux jeux de valeurs de paramètres à utiliser avec le operation, paramètre. Ce paramètre est obligatoire.
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. Entrez : str. Nom du catalogue. 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. Entrez : str. Nom du schéma. - Nom du champ : TABLE_CATALOG. Entrez : str. Catalogue auquel le schéma appartient. Aucune valeur renvoyée. Depuis la version 1.0 Paramètres : catalog_name Entrez : str Nom du catalogue à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Ce paramètre est facultatif. schema_name Entrez : str Nom du schéma à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Ce paramètre est facultatif.
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. Entrez : str. Catalogue auquel la table appartient. - Nom du champ : TABLE_SCHEM. Entrez : str. Schéma auquel la table appartient. - Nom du champ : TABLE_NAME. Entrez : str. Nom de la table. - Nom du champ : TABLE_TYPE. Entrez : str. 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). Aucune valeur renvoyée. Depuis la version 1.0 Paramètres catalog_name Entrez : str Nom du catalogue à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Ce paramètre est facultatif. schema_name Entrez : str Nom du schéma à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Ce paramètre est facultatif. table_name Entrez : str 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. Ce paramètre est facultatif. table_types Entrez : List[str] Liste de types de tables à mettre en correspondre, par exemple TABLE ou VIEW. Ce paramètre est facultatif.
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. Entrez : str. Catalogue auquel la colonne appartient. - Nom du champ : TABLE_SCHEM. Entrez : str. Schéma auquel la colonne appartient. - Nom du champ : TABLE_NAME. Entrez : str. Nom de la table à laquelle la colonne appartient. - Nom du champ : COLUMN_NAME. Entrez : str. Nom de la colonne. Aucune valeur renvoyée. Depuis la version 1.0 Paramètres : catalog_name Entrez : str Nom du catalogue à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Ce paramètre est facultatif. schema_name Entrez : str Nom du schéma à propos duquel récupérer des informations. Le caractère % est interprété comme un caractère générique. Ce paramètre est facultatif. table_name Entrez : str 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. Ce paramètre est facultatif. column_name Entrez : str 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. Ce paramètre est facultatif.
fetchall Obtient toutes les lignes (ou les lignes restantes) d’une requête. Aucun paramètre. Retourne toutes les lignes (ou toutes les lignes restantes) de la requête sous la forme d’un élément 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. 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é. Paramètres : size Entrez : int Nombre de lignes suivantes à récupérer. Ce paramètre est facultatif. S’il n’est pas spécifié, la valeur de l’attribut arraysize est utilisée. Exemple : cursor.fetchmany(10)
fetchone Obtient la ligne suivante du jeu de données. Aucun paramètre. Retourne la ligne suivante d’un jeu de données comme séquence unique en tant qu’objet Python tuple, ou retourne None s’il n’existe pas d’autres 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 en tant qu’objet Table PyArrow. Retourne jusqu’à l’argument size (ou l’attribut arraysize si size n’est pas spécifié) des lignes suivantes d’une requête sous la forme d’un objet Python PyArrow Objet 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 Paramètres : size Entrez : int Nombre de lignes suivantes à récupérer. Ce paramètre est facultatif. S’il n’est pas spécifié, la valeur de l’attribut arraysize est utilisée. Exemple : cursor.fetchmany_arrow(10)

Classe Row

La classe row est une structure de données de type tuple qui représente une ligne de résultat individuelle. 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 :

| 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.

Aucun paramètre.

Retourne un dict de champs. |

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

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 une liste verte d’adresses IP activée 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 Python
• Constantes intégrées (pour NoneType) sur le site web Python