Installera Databricks Connect för Python

Kommentar

Den här artikeln beskriver Databricks Connect för Databricks Runtime 13.3 LTS och senare.

I den här artikeln beskrivs hur du installerar Databricks Connect för Python. Se Vad är Databricks Connect?. Scala-versionen av den här artikeln finns i Installera Databricks Connect för Scala.

Krav

Om du vill installera Databricks Connect för Python måste följande krav uppfyllas:

• Om du ansluter till serverlös beräkning måste arbetsytan uppfylla kraven för serverlös beräkning.

• Om du ansluter till ett kluster måste målklustret uppfylla konfigurationskraven för klustret , vilket omfattar krav på Databricks Runtime-version.

• Du måste ha Python 3 installerat på utvecklingsdatorn och delversionen av Python som är installerad på utvecklingsdatorn måste uppfylla versionskrav i tabellen nedan.

  Databricks Connect-version	Typ av beräkning	Kompatibel Python-version
  15.1	Kluster	3.11
  15.1	Utan server	3,10
  13.3 LTS till 14.3 LTS	Kluster	3,10

• Om du vill använda PySpark-UDF:er måste utvecklingsdatorns installerade delversion av Python matcha den delversion av Python som ingår i Databricks Runtime som är installerad på klustret eller serverlös beräkning. Information om hur du hittar den lägre Python-versionen av klustret finns i avsnittet Systemmiljö i Viktig information om Databricks Runtime för klustret eller serverlös beräkning. Se Viktig information om versioner av Databricks Runtime och kompatibilitet och viktig information om serverlös beräkning.

Aktivera en virtuell Python-miljö

Databricks rekommenderar starkt att du har en virtuell Python-miljö aktiverad för varje Python-version som du använder med Databricks Connect. Virtuella Python-miljöer hjälper dig att se till att du använder rätt versioner av Python och Databricks Connect tillsammans. Mer information om dessa verktyg och hur du aktiverar dem finns i venv eller poesi.

Installera Databricks Connect-klienten

I det här avsnittet beskrivs hur du installerar Databricks Connect-klienten med venv eller poesi.

Kommentar

Om du redan har Databricks-tillägget för Visual Studio Code installerat behöver du inte följa de här installationsanvisningarna eftersom Databricks-tillägget för Visual Studio Code redan har inbyggt stöd för Databricks Connect för Databricks Runtime 13.3 LTS och senare. Hoppa till Felsök kod med hjälp av Databricks Connect för Databricks-tillägget för Visual Studio Code.

Installera Databricks Connect-klienten med venv

1. När den virtuella miljön är aktiverad avinstallerar du PySpark, om den redan är installerad, genom att uninstall köra kommandot . Detta krävs eftersom paketet står i databricks-connect konflikt med PySpark. Mer information finns i PySpark-installationer i konflikt. Kör kommandot för att kontrollera om PySpark redan är installerat show .

   # Is PySpark already installed?
   pip3 show pyspark
   
   # Uninstall PySpark
   pip3 uninstall pyspark
   

2. När den virtuella miljön fortfarande är aktiverad installerar du Databricks Connect-klienten genom att install köra kommandot . Använd alternativet --upgrade för att uppgradera en befintlig klientinstallation till den angivna versionen.

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

   Kommentar

   Databricks rekommenderar att du lägger till notationen "dot-asterisk" för att ange databricks-connect==X.Y.* i stället för databricks-connect=X.Y, för att se till att det senaste paketet är installerat. Detta är inte ett krav, men det hjälper dig att se till att du kan använda de senaste funktionerna som stöds för klustret.

Gå vidare till Konfigurera anslutningsegenskaper.

Installera Databricks Connect-klienten med Poetry

1. När den virtuella miljön är aktiverad avinstallerar du PySpark, om den redan är installerad, genom att remove köra kommandot . Detta krävs eftersom paketet står i databricks-connect konflikt med PySpark. Mer information finns i PySpark-installationer i konflikt. Kör kommandot för att kontrollera om PySpark redan är installerat show .

   # Is PySpark already installed?
   poetry show pyspark
   
   # Uninstall PySpark
   poetry remove pyspark
   

2. När den virtuella miljön fortfarande är aktiverad installerar du Databricks Connect-klienten genom att add köra kommandot .

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

   Kommentar

   Databricks rekommenderar att du använder notationen "at-tilde" för att ange databricks-connect@~14.3 i stället för databricks-connect==14.3, för att se till att det senaste paketet är installerat. Detta är inte ett krav, men det hjälper dig att se till att du kan använda de senaste funktionerna som stöds för klustret.

Konfigurera anslutningsegenskaper

I det här avsnittet konfigurerar du egenskaper för att upprätta en anslutning mellan Databricks Connect och ditt Azure Databricks-kluster eller serverlös beräkning, vilket omfattar följande:

• Instansnamnet för Azure Databricks-arbetsytan. Det här är värdet servervärdnamn för din beräkning. Se Hämta anslutningsinformation för en Azure Databricks-beräkningsresurs.
• Andra egenskaper som behövs för den Databricks-autentiseringstyp som du vill använda.

Kommentar

• OAuth-autentisering från användare till dator (U2M) stöds på Databricks SDK för Python 0.19.0 och senare. Du kan behöva uppdatera kodprojektets installerade version av Databricks SDK för Python till 0.19.0 eller senare för att använda OAuth U2M-autentisering. Se Kom igång med Databricks SDK för Python.

  För OAuth U2M-autentisering måste du använda Databricks CLI för att autentisera innan du kör Python-koden. Se Självstudien.

• OAuth-autentisering från dator till dator (M2M) autentisering med OAuth från dator till dator (M2M) stöds på Databricks SDK för Python 0.18.0 och senare. Du kan behöva uppdatera kodprojektets installerade version av Databricks SDK för Python till 0.18.0 eller senare för att använda OAuth M2M-autentisering. Se Kom igång med Databricks SDK för Python.

• Databricks SDK för Python har ännu inte implementerat Azure-hanterad identitetsautentisering.

Konfigurera en anslutning till ett kluster

För att konfigurera en anslutning till ett kluster behöver du klustrets ID. Du kan hämta kluster-ID:t från URL:en. Se Kluster-URL och ID.

Du kan konfigurera anslutningen till klustret på något av följande sätt. Databricks Connect söker efter konfigurationsegenskaper i följande ordning och använder den första konfigurationen som hittas. Avancerad konfigurationsinformation finns i Avancerad användning av Databricks Connect för Python.

1. DatabricksSession-klassens remote()-metod.
2. En Databricks-konfigurationsprofil
3. Miljövariabeln DATABRICKS_CONFIG_PROFILE
4. En miljövariabel för varje konfigurationsegenskap
5. En Databricks-konfigurationsprofil med namnet DEFAULT

Klassens DatabricksSession remote() metod

För det här alternativet, som endast gäller för autentisering med personlig åtkomsttoken i Azure Databricks, anger du namnet på arbetsytans instans, azure Databricks personliga åtkomsttoken och klustrets ID.

Du kan initiera klassen på DatabricksSession flera sätt på följande sätt:

• Ange fälten host, tokenoch cluster_id i DatabricksSession.builder.remote().
• Använd Databricks SDK:s Config klass.
• Ange en Databricks-konfigurationsprofil tillsammans med fältet cluster_id .
• Ange Spark Connect-niska veze i DatabricksSession.builder.remote().

I stället för att ange dessa anslutningsegenskaper i koden rekommenderar Databricks att du konfigurerar egenskaper via miljövariabler eller konfigurationsfiler enligt beskrivningen i det här avsnittet. I följande kodexempel förutsätts att du tillhandahåller en viss implementering av de föreslagna retrieve_* funktionerna för att hämta nödvändiga egenskaper från användaren eller från något annat konfigurationsarkiv, till exempel Azure KeyVault.

Koden för var och en av dessa metoder är följande:

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

En Databricks-konfigurationsprofil

För det här alternativet skapar eller identifierar du en Azure Databricks-konfigurationsprofil som innehåller fältet cluster_id och andra fält som behövs för den Databricks-autentiseringstyp som du vill använda.

De obligatoriska konfigurationsprofilfälten för varje autentiseringstyp är följande:

• För personlig åtkomsttokenautentisering i Azure Databricks: host och token.
• För OAuth-autentisering från dator till dator (M2M) (där det stöds): host, client_idoch client_secret.
• För OAuth-autentisering från användare till dator (U2M) (där det stöds): host.
• För Microsoft Entra-ID (tidigare Azure Active Directory)-tjänstens huvudnamnsautentisering: host, , azure_tenant_idazure_client_id, azure_client_secretoch eventuellt azure_workspace_resource_id.
• För Azure CLI-autentisering: host.
• För Azure-hanterad identitetsautentisering (där det stöds): host, azure_use_msi, azure_client_idoch eventuellt azure_workspace_resource_id.

Ange sedan namnet på den här konfigurationsprofilen via Config klassen.

Du kan ange cluster_id på några sätt på följande sätt:

• Inkludera fältet cluster_id i konfigurationsprofilen och ange sedan bara konfigurationsprofilens namn.
• Ange namnet på konfigurationsprofilen tillsammans med fältet cluster_id .

Om du redan har angett DATABRICKS_CLUSTER_ID miljövariabeln med klustrets ID behöver du inte heller ange cluster_id.

Koden för var och en av dessa metoder är följande:

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

Miljövariabeln DATABRICKS_CONFIG_PROFILE

För det här alternativet skapar eller identifierar du en Azure Databricks-konfigurationsprofil som innehåller fältet cluster_id och andra fält som behövs för den Databricks-autentiseringstyp som du vill använda.

Om du redan har angett DATABRICKS_CLUSTER_ID miljövariabeln med klustrets ID behöver du inte heller ange cluster_id.

De obligatoriska konfigurationsprofilfälten för varje autentiseringstyp är följande:

• För personlig åtkomsttokenautentisering i Azure Databricks: host och token.
• För OAuth-autentisering från dator till dator (M2M) (där det stöds): host, client_idoch client_secret.
• För OAuth-autentisering från användare till dator (U2M) (där det stöds): host.
• För Microsoft Entra-ID (tidigare Azure Active Directory)-tjänstens huvudnamnsautentisering: host, , azure_tenant_idazure_client_id, azure_client_secretoch eventuellt azure_workspace_resource_id.
• För Azure CLI-autentisering: host.
• För Azure-hanterad identitetsautentisering (där det stöds): host, azure_use_msi, azure_client_idoch eventuellt azure_workspace_resource_id.

DATABRICKS_CONFIG_PROFILE Ange miljövariabeln till namnet på den här konfigurationsprofilen. Initiera sedan klassen enligt DatabricksSession följande:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

En miljövariabel för varje konfigurationsegenskap

För det här alternativet anger DATABRICKS_CLUSTER_ID du miljövariabeln och eventuella andra miljövariabler som krävs för den Databricks-autentiseringstyp som du vill använda.

De miljövariabler som krävs för varje autentiseringstyp är följande:

• För personlig åtkomsttokenautentisering i Azure Databricks: DATABRICKS_HOST och DATABRICKS_TOKEN.
• För OAuth-autentisering från dator till dator (M2M) (där det stöds): DATABRICKS_HOST, DATABRICKS_CLIENT_IDoch DATABRICKS_CLIENT_SECRET.
• För OAuth-autentisering från användare till dator (U2M) (där det stöds): DATABRICKS_HOST.
• För Microsoft Entra-ID (tidigare Azure Active Directory)-tjänstens huvudnamnsautentisering: DATABRICKS_HOST, , ARM_TENANT_IDARM_CLIENT_ID, ARM_CLIENT_SECREToch eventuellt DATABRICKS_AZURE_RESOURCE_ID.
• För Azure CLI-autentisering: DATABRICKS_HOST.
• För Azure-hanterad identitetsautentisering (där det stöds): DATABRICKS_HOST, ARM_USE_MSI, ARM_CLIENT_IDoch eventuellt DATABRICKS_AZURE_RESOURCE_ID.

Initiera sedan klassen enligt DatabricksSession följande:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

En Databricks-konfigurationsprofil med namnet DEFAULT

För det här alternativet skapar eller identifierar du en Azure Databricks-konfigurationsprofil som innehåller fältet cluster_id och andra fält som behövs för den Databricks-autentiseringstyp som du vill använda.

Om du redan har angett DATABRICKS_CLUSTER_ID miljövariabeln med klustrets ID behöver du inte heller ange cluster_id.

De obligatoriska konfigurationsprofilfälten för varje autentiseringstyp är följande:

• För personlig åtkomsttokenautentisering i Azure Databricks: host och token.
• För OAuth-autentisering från dator till dator (M2M) (där det stöds): host, client_idoch client_secret.
• För OAuth-autentisering från användare till dator (U2M) (där det stöds): host.
• För Microsoft Entra-ID (tidigare Azure Active Directory)-tjänstens huvudnamnsautentisering: host, , azure_tenant_idazure_client_id, azure_client_secretoch eventuellt azure_workspace_resource_id.
• För Azure CLI-autentisering: host.
• För Azure-hanterad identitetsautentisering (där det stöds): host, azure_use_msi, azure_client_idoch eventuellt azure_workspace_resource_id.

Ge den här konfigurationsprofilen DEFAULTnamnet .

Initiera sedan klassen enligt DatabricksSession följande:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Konfigurera en anslutning till serverlös beräkning

Viktigt!

Den här funktionen finns som allmänt tillgänglig förhandsversion.

Databricks Connect stöder anslutning till serverlös beräkning. Om du vill använda den här funktionen måste kraven för att ansluta till serverlösa uppfyllas. Se Krav.

Viktigt!

Den här funktionen har följande begränsningar:

• Alla Databricks Connect för Python-begränsningar
• Alla serverlösa beräkningsbegränsningar
• Endast Python-beroenden som ingår som en del av en serverlös beräkningsmiljö kan användas för UDF:er. Se Systemmiljö. Det går inte att installera ytterligare beroenden.
• UDF:er med anpassade moduler stöds inte.

Du kan konfigurera en anslutning till serverlös beräkning på något av följande sätt:

• Ange variabeln DATABRICKS_SERVERLESS_COMPUTE_ID för lokal miljö till auto. Om den här miljövariabeln har angetts cluster_idignorerar Databricks Connect .

• I en lokal Databricks-konfigurationsprofil anger du serverless_compute_id = autooch refererar sedan till profilen från Din Databricks Connect Python-kod.

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

• Alternativt kan du bara uppdatera Din Databricks Connect Python-kod enligt följande:

  from databricks.connect import DatabricksSession as SparkSession
  
  spark = DatabricksSession.builder.serverless(True).getOrCreate()
  

  from databricks.connect import DatabricksSession as SparkSession
  
  spark DatabricksSession.builder.remote(serverless=True).getOrCreate()
  

Kommentar

Den serverlösa beräkningssessionen överskrider tidsgränsen efter 10 minuters inaktivitet. Därefter måste Python-processen startas om på klientsidan för att skapa en ny Spark-session för att ansluta till serverlös beräkning.

Verifiera anslutningen till Databricks

Om du vill verifiera din miljö, är standardautentiseringsuppgifterna och anslutningen till beräkning korrekt konfigurerade för Databricks Connect genom att köra databricks-connect test kommandot, som misslyckas med en slutkod som inte är noll och ett motsvarande felmeddelande när den identifierar eventuell inkompatibilitet i installationen.

databricks-connect test

Du kan också använda gränssnittet pyspark som ingår som en del av Databricks Connect för Python och köra ett enkelt kommando. Mer information om PySpark-gränssnittet finns i Pyspark Shell.