Compartir vía

Instalar Databricks Connect para Python

  • Artículo

Nota:

Este artículo describe Databricks Connect para Databricks Runtime 13.3 LTS y versiones posteriores.

En este artículo se describe cómo instalar Databricks Connect para Python. Consulte ¿Qué es Databricks Connect? Para obtener la versión de Scala de este artículo, consulte Instalar Databricks Connect para Scala.

Requisitos

Para instalar Databricks Connect para Python, se deben cumplir los siguientes requisitos:

  • Si se conecta al proceso sin servidor, el área de trabajo debe cumplir los requisitos de proceso sin servidor.

    Nota:

    El proceso sin servidor se admite en Databricks Connect versión 15.1 y posteriores. Además, las versiones de Databricks Connect iguales o anteriores a la versión de Databricks Runtime en sin servidor son totalmente compatibles. Consulte las Notas de la versión. Para comprobar si la versión de Databricks Connect es compatible con el proceso sin servidor, consulte Validación de la conexión a Databricks.

  • Si se conecta a un clúster, el clúster de destino debe cumplir los requisitos de configuración del clúster, que incluye los requisitos de versión de Databricks Runtime.

  • Debe tener Python 3 instalado en la máquina de desarrollo y la versión secundaria de Python instalada en la máquina de desarrollo debe cumplir los requisitos de versión de la tabla siguiente.

    Compute type (Tipo de proceso) Versión de Databricks Connect Versión compatible de Python
    Sin servidor 15.1 y versiones posteriores 3,11
    Clúster 15.1 y versiones posteriores 3,11
    Clúster 13.3 LTS a 14.3 LTS 3.10

  • Si desea usar UDF de PySpark, la versión secundaria instalada de la máquina de desarrollo de Python debe coincidir con la versión secundaria de Python que se incluye con Databricks Runtime instalado en el clúster o el proceso sin servidor. Para buscar la versión secundaria de Python del clúster, consulte la sección Entorno del sistema de las notas de la versión de Databricks Runtime para el clúster o el proceso sin servidor. Consulte Notas de la versión de Databricks Runtime y compatibilidad y Notas de la versión de proceso sin servidor.

Activar un entorno virtual de Python

Databricks recomienda que tenga un entorno virtual de Python activado para cada versión de Python que use con Databricks Connect. Los entornos virtuales de Python ayudan a garantizar que usa las versiones correctas de Python y Databricks Connect juntas. Para obtener más información sobre estas herramientas y cómo activarlas, consulte venv o Poetry.

Instale el cliente de Databricks Connect

En esta sección se describe cómo instalar el cliente de Databricks Connect con venv o Poetry.

Nota:

Si ya tiene instalada la extensión Databricks para Visual Studio Code, no es necesario seguir estas instrucciones de configuración, ya que la extensión Databricks para Visual Studio Code ya tiene compatibilidad integrada con Databricks Connect para Databricks Runtime 13.3 LTS y versiones posteriores. Vaya a Depuración de código mediante Databricks Connect para la extensión de Databricks para Visual Studio Code.

Instalación del cliente de Databricks Connect con venv

  1. Con el entorno virtual activado, desinstale PySpark, si ya está instalado, ejecutando el comando uninstall. Esto es necesario porque el paquete databricks-connect entra en conflicto con PySpark. Para información detallada, consulte Instalaciones de PySpark en conflicto. Para comprobar si PySpark ya está instalado, ejecute el comando show.

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Con el entorno virtual aún activado, instale el cliente de Databricks Connect mediante la ejecución del comando install. Use la opción --upgrade para actualizar cualquier instalación de cliente existente a la versión especificada.

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

    Nota:

    Databricks recomienda anexar la notación "dot-asterisk" para especificar databricks-connect==X.Y.* en lugar de databricks-connect=X.Y, para asegurarse de que está instalado el paquete más reciente. Aunque esto no es un requisito, permite asegurarse de que puede usar las características más recientes que admite ese clúster.

Vaya directamente a Configurar las propiedades de conexión.

Instalación del cliente de Databricks Connect con Poetry

  1. Con el entorno virtual activado, desinstale PySpark, si ya está instalado, ejecutando el comando remove. Esto es necesario porque el paquete databricks-connect entra en conflicto con PySpark. Para información detallada, consulte Instalaciones de PySpark en conflicto. Para comprobar si PySpark ya está instalado, ejecute el comando show.

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Con el entorno virtual aún activado, instale el cliente de Databricks Connect mediante la ejecución del comando add.

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

    Nota:

    Databricks recomienda usar la “notación at-tilde” para especificar databricks-connect@~15.4 en lugar de databricks-connect==15.4, para asegurarse de que el paquete más reciente está instalado. Aunque esto no es un requisito, permite asegurarse de que puede usar las características más recientes que admite ese clúster.

Configurar propiedades de conexión

En esta sección, configurará las propiedades para establecer una conexión entre Databricks Connect y el clúster de Azure Databricks o el proceso sin servidor, que incluye lo siguiente:

Nota:

Configurar una conexión a un clúster

Para configurar una conexión a un clúster, necesitará el id. del clúster. Puede obtenerlo de la dirección URL. Consulte Dirección URL e identificador del clúster.

Puede configurar la conexión al clúster de una de las maneras siguientes. Databricks Connect busca propiedades de configuración en el orden siguiente y usa la primera configuración que encuentra. Para obtener información de configuración avanzada, consulte Uso avanzado de Databricks Connect para Python.

  1. Método remote() de la clase DatabricksSession.
  2. Un perfil de configuración de Databricks
  3. La variable de entorno DATABRICKS_CONFIG_PROFILE
  4. Una variable de entorno para cada propiedad de configuración
  5. Un perfil de configuración de Azure Databricks denominado DEFAULT

El método remote() de la clase DatabricksSession

Para esta opción, que solo se aplica a la autenticación de token de acceso personal de Azure Databricks, especifica el nombre de la instancia del área de trabajo, el token de acceso personal de Azure Databricks y el identificador del clúster.

Puede inicializar la clase DatabricksSession de varias maneras, como se indica a continuación:

  • Establezca los campos host, token y cluster_id en DatabricksSession.builder.remote().
  • Use la clase Config del SDK de Databricks.
  • Especifique un perfil de configuración de Databricks junto con el campo cluster_id.
  • Establezca la cadena de conexión de Spark Connect en DatabricksSession.builder.remote().

En lugar de especificar estas propiedades de conexión en el código, Databricks recomienda configurar las propiedades mediante las variables de entorno o los archivos de configuración, como se describe en esta sección. En los ejemplos de código siguientes se supone que se proporciona alguna implementación de las funciones propuestas de retrieve_* para obtener las propiedades necesarias del usuario o de algún otro almacén de configuración, como Azure KeyVault.

El código de cada uno de estos enfoques es el siguiente:

# 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 perfil de configuración de Databricks

En el caso de esta opción, cree o identifique un perfil de configuración de Azure Databricks que contenga el campo cluster_id y cualquier otro campo necesario para el tipo de autenticación de Databricks que quiere usar.

Los campos de perfil de configuración necesarios para cada tipo de autenticación son los siguientes:

Luego, establezca el nombre de este perfil de configuración mediante la clase Config.

Puede especificar cluster_id de varias maneras, como se indica a continuación:

  • Incluya el campo cluster_id en el perfil de configuración y, luego, especifique el nombre del perfil de configuración.
  • Especifique el nombre del perfil de configuración junto con el campo cluster_id.

Si ya ha establecido la variable de entorno DATABRICKS_CLUSTER_ID con el identificador del clúster, no es necesario también especificar cluster_id.

El código de cada uno de estos enfoques es el siguiente:

# 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 de entorno DATABRICKS_CONFIG_PROFILE

En el caso de esta opción, cree o identifique un perfil de configuración de Azure Databricks que contenga el campo cluster_id y cualquier otro campo necesario para el tipo de autenticación de Databricks que quiere usar.

Si ya ha establecido la variable de entorno DATABRICKS_CLUSTER_ID con el identificador del clúster, no es necesario también especificar cluster_id.

Los campos de perfil de configuración necesarios para cada tipo de autenticación son los siguientes:

Establezca la variable de entorno DATABRICKS_CONFIG_PROFILE con el nombre de este perfil de configuración. Y, a continuación, inicialice la clase DatabricksSession como se indica:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Una variable de entorno para cada propiedad de configuración

En esta opción, establezca la variable de entorno DATABRICKS_CLUSTER_ID y cualquier otra variable de entorno necesaria para el tipo de autenticación de Databricks que quiere usar.

Las variables de entorno necesarias para cada tipo de autenticación son las siguientes:

Y, a continuación, inicialice la clase DatabricksSession como se indica:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Un perfil de configuración de Databricks denominado DEFAULT

En el caso de esta opción, cree o identifique un perfil de configuración de Azure Databricks que contenga el campo cluster_id y cualquier otro campo necesario para el tipo de autenticación de Databricks que quiere usar.

Si ya ha establecido la variable de entorno DATABRICKS_CLUSTER_ID con el identificador del clúster, no es necesario también especificar cluster_id.

Los campos de perfil de configuración necesarios para cada tipo de autenticación son los siguientes:

Asigne a este perfil de configuración el nombre DEFAULT.

Y, a continuación, inicialice la clase DatabricksSession como se indica:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Configurar conexiones a procesos sin servidor

Importante

Esta característica está en versión preliminar pública.

Databricks Connect admite la conexión a un proceso sin servidor. Para usar esta característica, se deben cumplir los requisitos para conectarse a procesos sin servidor. Vea Requisitos.

Importante

Esta característica tiene las siguientes limitaciones:

Puede configurar una conexión a un proceso sin servidor de una de las maneras siguientes:

  • Establezca la variable de entorno local DATABRICKS_SERVERLESS_COMPUTE_ID en auto. Si se establece esta variable de entorno, Databricks Connect omite el cluster_id.

  • En un perfil de configuración local de Databricks, establezca serverless_compute_id = autoy, a continuación, haga referencia a ese perfil desde el código de Python de Databricks Connect.

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

  • Como alternativa, solo tiene que actualizar el código de Python de Databricks Connect de la siguiente manera:

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

Nota:

La sesión de proceso sin servidor agota el tiempo de espera después de 10 minutos de inactividad. Después de esto, se debe crear una nueva sesión de Spark para conectarse al proceso sin servidor. Esto se puede hacer con spark = DatabricksSession.builder.serverless(True).getOrCreate().

Validar la conexión a Databricks

Para validar el entorno, las credenciales predeterminadas y la conexión al proceso están configuradas correctamente para Databricks Connect, ejecute el comando databricks-connect test, que produce un error con un código de salida distinto de cero y un mensaje de error correspondiente cuando detecta cualquier incompatibilidad en la configuración.

databricks-connect test

También puede validar el entorno en el código de Python mediante validateSession():

DatabricksSession.builder.validateSession(True).getOrCreate()