Installer Databricks Connect pour Python

  • Article

Remarque

Cet article traite de Databricks Connect pour Databricks Runtime 13.0 et versions ultérieures.

Cet article explique comment installer Databricks Connect pour Python. Consultez Qu’est-ce que Databricks Connect ?. Pour la version Scala de cet article, consultez Installer Databricks Connect pour Scala.

Spécifications

  • Votre cluster et votre espace de travail Azure Databricks cibles doivent répondre aux exigences de Configuration de cluster pour Databricks Connect.

  • Vous devez installer Python 3 sur votre machine de développement et la version mineure de votre installation cliente de Python doit être identique à la version Python mineure de votre cluster Azure Databricks. Pour trouver la version mineure de Python de votre cluster, consultez la section « Environnement système » des notes de publication de Databricks Runtime pour votre cluster. Consultez Notes de publication, versions et compatibilité de Databricks Runtime.

    Remarque

    Si vous souhaitez utiliser les UDF PySpark, il est important que la version mineure de Python installée par votre machine de développement corresponde à la version mineure de Python installée sur le cluster et incluse avec Databricks Runtime.

  • La version de package majeure et mineure de Databricks Connect doit toujours correspondre à votre version de Databricks Runtime. Databricks vous recommande de toujours utiliser le package le plus récent de Databricks Connect qui correspond à votre version de Databricks Runtime. Par exemple, quand vous utilisez un cluster Databricks Runtime 14.0, vous devez également utiliser la version 14.0 du package databricks-connect.

    Remarque

    Consultez les notes de publication de Databricks Connect pour obtenir la liste des versions et des mises à jour de maintenance de Databricks Connect.

    Il n’est pas obligatoire d’utiliser le package Databricks Connect le plus récent qui correspond à votre version de Databricks Runtime. Pour Databricks Runtime 13.3 LTS et versions ultérieures, vous pouvez utiliser le package Databricks Connect avec toutes les versions de Databricks Runtime identiques ou postérieures à la version du package Databricks Connect. Toutefois, si vous souhaitez utiliser les fonctionnalités disponibles dans les versions ultérieures de Databricks Runtime, vous devez mettre à niveau le package Databricks Connect en conséquence.

  • Databricks recommande vivement d’avoir un environnement virtuel Python activé pour chaque projet de code Python que vous utilisez avec Databricks Connect. Les environnements virtuels Python garantissent que vous utilisez les bonnes versions de Python et Databricks Connect ensemble. Cela peut aider à diminuer ou raccourcir la résolution des problèmes techniques associés. Découvrez comment activer un environnement virtuel Python pour venv ou Poetry dans les sections suivantes. Pour plus d’informations sur ces outils, consultez venv ou Poetry.

Activer un environnement virtuel Python avec venv

Si vous utilisez venv sur votre machine de développement, et si votre cluster exécute Python 3.10, vous devez créer un environnement venv avec cette version. L’exemple de commande suivant génère les scripts pour activer un environnement venv avec Python 3.10, puis cette commande place ces scripts dans un dossier masqué nommé .venv dans le répertoire de travail actuel :

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

Afin d’utiliser ces scripts pour activer cet environnement venv, consultez la page Fonctionnement des venvs.

Passez à Configurer le client.

Activer un environnement virtuel Python avec Poetry

  1. Installez Poetry, si ce n’est pas encore fait.

  2. Si vous utilisez Poetry sur votre machine de développement, et si votre cluster exécute Python 3.10, vous devez créer un environnement virtuel Poetry avec cette version. Dans le répertoire racine de votre projet de code Python existant, demandez à poetry d’initialiser votre projet de code Python pour Poetry en exécutant la commande suivante :

    poetry init

  3. Poetry affiche plusieurs invites pour vous permettre de terminer. Aucune de ces invites n’est spécifique à Databricks Connect. Pour plus d’informations sur ces invites, consultez init.

  4. Une fois les invites terminées, Poetry ajoute un fichier pyproject.toml à votre projet Python. Pour plus d’informations sur le fichier pyproject.toml, consultez le fichier pyproject.toml.

  5. Dans le répertoire racine de votre projet de code Python, demandez à poetry de lire le fichier pyproject.toml, de résoudre les dépendances et de les installer, de créer un fichier poetry.lock pour verrouiller ces dépendances, et enfin de créer un environnement virtuel. Pour ce faire, exécutez la commande suivante :

    poetry install

  6. Dans le répertoire racine de votre projet de code Python, indiquez à poetry d’activer l’environnement virtuel, puis entrez l’interpréteur de commandes. Pour ce faire, exécutez la commande suivante :

    poetry shell

Vous saurez que votre environnement virtuel est activé, et que l’interpréteur de commandes est entré quand le nom de l’environnement virtuel s’affichera entre parenthèses juste avant l’invite de terminal, par exemple (my-project-py3.10).

Pour désactiver l’environnement virtuel et quitter l’interpréteur de commandes à tout moment, exécutez la commande exit.

Vous savez que vous avez quitté l’interpréteur de commandes quand le nom de l’environnement virtuel ne s’affiche plus entre parenthèses juste avant l’invite de terminal.

Pour plus d’informations sur la création et la gestion d’environnements virtuels Poetry, consultez Gestion des environnements.

Configurer le client

Conseil

Si vous avez déjà installé l’extension Databricks pour Visual Studio Code, vous n’avez pas besoin de suivre ces instructions d’installation.

L’extension Databricks pour Visual Studio Code offre déjà une prise en charge intégrée de Databricks Connect pour Databricks Runtime 13.0 et versions ultérieures. Passez à l’étape Déboguer du code à l’aide de Databricks Connect pour l’extension Databricks pour Visual Studio Code.

Après avoir répondu aux exigences de Databricks Connect, effectuez les étapes suivantes pour configurer le client Databricks Connect.

Étape 1 : Installer le client Databricks Connect

Ces sections expliquent comment installer le client Databricks Connect avec venv ou Poetry.

Installer le client Databricks Connect avec venv

  1. Une fois votre environnement virtuel activé, désinstallez PySpark, s’il est déjà installé, en exécutant la commande uninstall. Cela est nécessaire car le package databricks-connect est en conflit avec PySpark. Pour plus d’informations, consultez Installations PySpark en conflit. Pour vérifier si PySpark est déjà installé, exécutez la commande show.

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Votre environnement virtuel étant toujours activé, installez le client Databricks Connect en exécutant la commande install. Utilisez l’option --upgrade pour mettre à niveau toute installation de client existante vers la version spécifiée.

    pip3 install --upgrade "databricks-connect==14.0.*"  # Or X.Y.* to match your cluster version.

    Notes

    Databricks vous recommande d’ajouter la notation « point-astérisque » pour spécifier databricks-connect==X.Y.* au lieu de databricks-connect=X.Y et vous assurer que le package le plus récent est installé. Bien qu’il ne s’agit pas d’une exigence, cela vous permet de vous assurer que vous pouvez utiliser les dernières fonctionnalités prises en charge pour ce cluster.

Passez à l’Étape 2 : Configurer les propriétés de la connexion.

Installer le client Databricks Connect avec Poetry

  1. Une fois votre environnement virtuel activé, désinstallez PySpark, s’il est déjà installé, en exécutant la commande remove. Cela est nécessaire car le package databricks-connect est en conflit avec PySpark. Pour plus d’informations, consultez Installations PySpark en conflit. Pour vérifier si PySpark est déjà installé, exécutez la commande show.

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Votre environnement virtuel étant toujours activé, installez le client Databricks Connect en exécutant la commande add.

    poetry add databricks-connect@~14.0  # Or X.Y to match your cluster version.

    Remarque

    Databricks vous recommande d’utiliser la notation « arobase-tilde » pour spécifier databricks-connect@~14.0 à la place de databricks-connect==14.0, afin de vérifier que le package le plus récent est installé. Bien qu’il ne s’agit pas d’une exigence, cela vous permet de vous assurer que vous pouvez utiliser les dernières fonctionnalités prises en charge pour ce cluster.

Étape 2 : Configurer les propriétés de connexion

Dans cette section, vous allez configurer des propriétés pour établir une connexion entre Databricks Connect et votre cluster Azure Databricks distant. Ces propriétés comprennent des paramètres permettant d’authentifier Databricks Connect avec votre cluster.

À partir de Databricks Connect pour Databricks Runtime 13.1 et versions ultérieures, Databricks Connect inclut le kit SDK Databricks pour Python. Ce SDK implémente la norme d’authentification unifiée du client Databricks, une approche architecturale et programmatique consolidée et cohérente pour l’authentification. Cette approche permet de configurer et d’automatiser l’authentification avec Azure Databricks de façon plus centralisée et prévisible. Elle vous permet de configurer une seule fois l’authentification Azure Databricks, puis d’utiliser cette configuration sur plusieurs outils Azure Databricks et SDK sans modifier à nouveau la configuration de l’authentification.

Remarque

  1. Collectez les propriétés de configuration suivantes.

  2. Configurez la connexion dans votre code. Databricks Connect recherche les propriétés de configuration dans l’ordre suivant jusqu’à ce qu’il les trouve. Une fois qu’il les a trouvées, il cesse de rechercher parmi les options restantes. Les détails de chaque option apparaissent après le tableau suivant :

    Options des propriétés de configuration S’applique à
    1. La classe DatabricksSession de la méthode remote() Authentification unique à l’aide d’un jeton d’accès personnel Azure Databricks
    2. Un profil de configuration Azure Databricks Tous les types d’authentification Azure Databricks pris en charge
    3. La variable d’environnement SPARK_REMOTE Authentification unique à l’aide d’un jeton d’accès personnel Azure Databricks
    4. La variable d’environnement DATABRICKS_CONFIG_PROFILE Tous les types d’authentification Azure Databricks pris en charge
    5. Une variable d’environnement pour chaque propriété de connexion Tous les types d’authentification Azure Databricks pris en charge
    6. Un profil de configuration Azure Databricks nommé DEFAULT Tous les types d’authentification Azure Databricks pris en charge

    1. La classe DatabricksSession de la méthode remote()

      Pour cette option, qui s’applique uniquement à l’authentification par jetons d’accès personnels Azure Databricks, spécifiez le nom d’instance de l’espace de travail, le jeton d’accès personnel Azure Databricks et l’ID du cluster.

      Vous pouvez initialiser la classe DatabricksSession de plusieurs façons, comme suit :

      • Définissez les champs et host, token et cluster_id dans DatabricksSession.builder.remote().
      • Utilisez la classe Config du Kit de développement logiciel (SDK) de Databricks.
      • Spécifiez un profil de configuration Databricks avec le champ cluster_id.
      • Définissez la chaîne de connexion Spark Connect dans DatabricksSession.builder.remote().

      Databricks déconseille de spécifier directement ces propriétés de connexion dans votre code. À la place, Databricks recommande de configurer les propriétés via des variables d’environnement ou des fichiers config, comme indiqué tout au long de cette section. Les exemples de code suivants considèrent que vous fournissez vous-même une implémentation des fonctions retrieve_* proposées pour obtenir les propriétés nécessaires auprès de l’utilisateur ou d’une autre banque de configuration, comme Azure KeyVault.

      Le code de chacune de ces approches est le suivant :

      # Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).getOrCreate()

    2. Un profil de configuration Azure Databricks

      Pour cette option, créez ou identifiez un profil de configuration Azure Databricks contenant le champ cluster_id et tout autre champ nécessaire pour le type d’authentification Databricks que vous souhaitez utiliser.

      Les champs de profil de configuration requis pour chaque type d'authentification sont les suivants :

      Définissez ensuite le nom de ce profil de configuration via la classe Config.

      Vous pouvez spécifier cluster_id de plusieurs façons, comme suit :

      • Incluez le champ cluster_id dans votre profil de configuration, puis spécifiez simplement le nom du profil de configuration.
      • Spécifiez le nom du profil de configuration avec le champ cluster_id.

      Si vous avez déjà défini la variable d’environnement DATABRICKS_CLUSTER_ID avec l’ID du cluster, vous n’avez pas besoin de spécifier cluster_id.

      Le code de chacune de ces approches est le suivant :

      # Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

    3. Variable d’environnement SPARK_REMOTE

      Pour cette option, qui s’applique uniquement à l’authentification par jetons d’accès personnels Azure Databricks , définissez la variable d’environnement SPARK_REMOTE sur la chaîne suivante, en remplaçant les espaces réservés par les valeurs appropriées.

      sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>

      Puis initialisez la classe DatabricksSession comme suit :

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

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

    4. Variable d’environnement DATABRICKS_CONFIG_PROFILE

      Pour cette option, créez ou identifiez un profil de configuration Azure Databricks contenant le champ cluster_id et tout autre champ nécessaire pour le type d’authentification Databricks que vous souhaitez utiliser.

      Si vous avez déjà défini la variable d’environnement DATABRICKS_CLUSTER_ID avec l’ID du cluster, vous n’avez pas besoin de spécifier cluster_id.

      Les champs de profil de configuration requis pour chaque type d'authentification sont les suivants :

      Attribuez à la variable d’environnement DATABRICKS_CONFIG_PROFILE le nom de ce profil de configuration. Puis initialisez la classe DatabricksSession comme suit :

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

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

    5. Une variable d’environnement pour chaque propriété de connexion

      Pour cette option, définissez la variable d'environnement DATABRICKS_CLUSTER_ID ainsi que les autres variables d’environnement nécessaires pour le type d’authentification Databricks que vous souhaitez utiliser.

      Les variables d'environnement requises pour chaque type d'authentification sont les suivantes :

      Puis initialisez la classe DatabricksSession comme suit :

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

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

    6. Profil de configuration Azure Databricks nommé DEFAULT

      Pour cette option, créez ou identifiez un profil de configuration Azure Databricks contenant le champ cluster_id et tout autre champ nécessaire pour le type d’authentification Databricks que vous souhaitez utiliser.

      Si vous avez déjà défini la variable d’environnement DATABRICKS_CLUSTER_ID avec l’ID du cluster, vous n’avez pas besoin de spécifier cluster_id.

      Les champs de profil de configuration requis pour chaque type d'authentification sont les suivants :

      Nommez ce profil de configuration DEFAULT.

      Puis initialisez la classe DatabricksSession comme suit :

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. Vérifier votre environnement et la connexion au cluster Databricks

    • La commande suivante vérifie que votre environnement, les informations d’identification par défaut et la connexion au cluster sont toutes correctement configurées pour Databricks Connect.

      databricks-connect test

      Cette commande récupère les informations d’identification par défaut configurées sur l’environnement (comme le profil de configuration DEFAULT ou via des variables d’environnement).

      La commande échoue avec un code de sortie non nul et un message d’erreur correspondant quand elle détecte une incompatibilité dans la configuration.

    • En outre, vous pouvez aussi utiliser le shell pyspark qui est inclus dans le cadre de Databricks Connect pour Python. Démarrez le shell en exécutant :

      pyspark

      L’interpréteur de commandes Spark s’affiche, par exemple :

      Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>

      À l’invite >>>, exécutez une commande PySpark simple, telle que spark.range(1,10).show(). S’il n’y a pas d’erreur, vous vous êtes connecté.

      Si vous vous êtes connecté, pour arrêter l’interpréteur de commandes Spark, appuyez sur Ctrl + d ou Ctrl + z, ou exécutez la commande quit() ou exit().

      Pour plus d’informations sur le fichier binaire databricks-connect, consultez Utilisation avancée de Databricks Connect pour Python.