Connecteur Databricks SQL pour Python

Article
11/14/2024

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 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 les jetons d’accès personnels Azure Databricks 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_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 :

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

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

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

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

Partager via

Connecteur Databricks SQL pour Python

Spécifications

Bien démarrer

Cluster

Entrepôt SQL

Authentification

Authentification par jeton d’accès personnel Databricks

Authentification OAuth machine à machine (M2M)

Authentification par jeton Microsoft Entra ID

Authentification utilisateur à machine (U2M) OAuth

Exemples

Interroger des données

Insertion 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

Configuration de la journalisation

Test

Informations de référence sur l'API

Package

Module

Classes

Classe `Connection`

Classe `Cursor`

Classe `Row`

Conversions des types

Dépannage

`tokenAuthWrapperInvalidAccessToken: Invalid access token`, message

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

`IpAclError`, message

Ressources supplémentaires

Commentaires

Ressources supplémentaires

Partager via

Connecteur Databricks SQL pour Python

Spécifications

Bien démarrer

Cluster

Entrepôt SQL

Authentification

Authentification par jeton d’accès personnel Databricks

Authentification OAuth machine à machine (M2M)

Authentification par jeton Microsoft Entra ID

Authentification utilisateur à machine (U2M) OAuth

Exemples

Interroger des données

Insertion 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

Configuration de la journalisation

Test

Informations de référence sur l'API

Package

Module

Classes

Classe Connection

Classe Cursor

Classe Row

Conversions des types

Dépannage

tokenAuthWrapperInvalidAccessToken: Invalid access token, message

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

IpAclError, message

Ressources supplémentaires

Commentaires

Ressources supplémentaires

Classe `Connection`

Classe `Cursor`

Classe `Row`

`tokenAuthWrapperInvalidAccessToken: Invalid access token`, message

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

`IpAclError`, message