Partager via

Installer Databricks Connect pour Python

  • Article

Remarque

Cet article présente Databricks Connect pour Databricks Runtime 13.3 LTS et les 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

Pour installer Databricks Connect pour Python, les exigences suivantes doivent être satisfaites :

  • Si vous vous connectez au calcul serverless, votre espace de travail doit répondre aux exigences du calcul serverless.

  • Si vous vous connectez à un cluster, votre cluster cible doit répondre aux exigences de configuration de cluster, ce qui inclut les exigences de version de Databricks Runtime.

  • Python 3 doit être installé sur votre machine de développement, et la version mineure de Python installée sur votre machine de développement doit répondre aux exigences de version du tableau ci-dessous.

    Version de Databricks Connect Type de capacité de calcul Version Python compatible
    15,3 Cluster 3.11
    15.2 Cluster 3.11
    15,1 Cluster 3.11
    15,1 Sans serveur 3.10
    13.3 LTS à 14.3 LTS Cluster 3.10

  • Si vous souhaitez utiliser les UDF PySpark, la version mineure de Python installée sur votre machine de développement doit correspondre à la version mineure de Python incluse avec le Databricks Runtime installé sur le cluster ou le calcul serverless. Pour trouver la version mineure de Python de votre cluster, consultez la section Environnement systèmedes notes de publication de Databricks Runtime pour votre cluster ou calcul serverless. Consultez Versions des notes de publication Databricks Runtime et compatibilité et Notes de publication du calcul serverless.

Activer un environnement virtuel Python

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. Pour plus d’informations sur ces outils et sur la façon de les activer, consultez venv ou Poetry.

Installer le client Databricks Connect

Cette section explique comment installer le client Databricks Connect avec venv ou Poetry.

Remarque

Si vous avez déjà installé l’extension Databricks pour Visual Studio Code, vous n’avez pas besoin de suivre ces instructions d’installation, car l’extension Databricks pour Visual Studio Code a déjà une prise en charge intégrée de Databricks Connect pour Databricks Runtime 13.3 LTS et les versions ultérieures. Passez à Déboguer du code en utilisant Databricks Connect pour l’extension Databricks pour Visual Studio Code.

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.3.*"  # 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 à Configurer les propriétés de 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.3  # Or X.Y to match your cluster version.

    Remarque

    Databricks vous recommande d’utiliser la notation « arobase-tilde » pour spécifier databricks-connect@~14.3 à la place de databricks-connect==14.3, 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.

Configurer les propriétés de connexion

Dans cette section, vous configurez des propriétés pour établir une connexion entre Databricks Connect et votre cluster Azure Databricks ou votre calcul serverless, qui inclut les éléments suivants :

Remarque

Configurer une connexion à un cluster

Pour configurer une connexion à un cluster, vous aurez besoin de l’ID de votre cluster. Vous pouvez obtenir l’ID du cluster à partir de l’URL. Consultez URL et ID du cluster.

Vous pouvez configurer la connexion à votre cluster de l’une des manières suivantes. Databricks Connect recherche les propriétés de configuration dans l’ordre suivant et utilise la première configuration trouvée. Pour obtenir des informations sur la configuration avancée, consultez Utilisation avancée de Databricks Connect pour Python.

  1. La méthode remote() de la classe DatabricksSession.
  2. Un profil de configuration Databricks
  3. La variable d’environnement DATABRICKS_CONFIG_PROFILE
  4. Une variable d’environnement pour chaque propriété de connexion
  5. Un profil de configuration Azure Databricks nommé DÉFAUT

La méthode remote() de la classe DatabricksSession

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

Au lieu de spécifier ces propriétés de connexion dans votre code, Databricks recommande de configurer les propriétés via des variables d’environnement ou des fichiers de configuration, comme décrit dans cette section. Les exemples de code suivants considèrent que vous fournissez une implémentation des fonctions retrieve_* proposées pour obtenir les propriétés nécessaires auprès de l’utilisateur ou d’un autre magasin 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()

Un profil de configuration 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()

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

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

Un profil de configuration 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()

Configurer une connexion au calcul serverless

Important

Cette fonctionnalité est disponible en préversion publique.

Databricks Connect prend en charge la connexion au calcul serverless. Pour utiliser cette fonctionnalité, les exigences de connexion à serverless doivent être satisfaites. Consultez Spécifications.

Important

Cette fonctionnalité présente les limitations suivantes :

Vous pouvez configurer une connexion au calcul serverless de l’une des manières suivantes :

  • Définissez la variable d’environnement locale DATABRICKS_SERVERLESS_COMPUTE_ID sur auto. Si cette variable d’environnement est définie, Databricks Connect ignore le cluster_id.

  • Dans un profil de configuration Databricks local, définissez serverless_compute_id = auto, puis référencez ce profil depuis votre code Python Databricks Connect.

    [DEFAULT]
host = https://my-workspace.cloud.databricks.com/
serverless_compute_id = auto
token = dapi123...

  • Vous pouvez également mettre à jour votre code Python Databricks Connect comme suit :

    from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.serverless(True).getOrCreate()

    from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(serverless=True).getOrCreate()

Remarque

La session de calcul serverless expire après 10 minutes d’inactivité. Après cela, le processus Python doit être redémarré côté client pour créer une session Spark afin de se connecter au calcul serverless.

Valider la connexion à Databricks

Pour valider que votre environnement, vos informations d’identification par défaut et votre connexion au calcul sont correctement configurés pour Databricks Connect, exécutez la commande databricks-connect test, qui échoue avec un code de sortie non nul et un message d’erreur correspondant lorsqu’elle détecte toute incompatibilité dans l’installation.

databricks-connect test

Vous pouvez également utiliser l’interpréteur de commandes pyspark inclus comme élément de Databricks Connect pour Python et exécuter une commande simple. Pour plus d’informations sur l’interpréteur de commandes PySpark, consultez Interpréteur de commandes Pyspark.