Compartir a través de

Instalar Databricks Connect para Python

  • Artículo

Nota:

En este artículo se trata Databricks Connect para Databricks Runtime 13.0 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

  • El área de trabajo y el clúster de Azure Databricks de destino deben cumplir los requisitos de la configuración de un clúster para Databricks Connect.

  • Debe instalar Python 3 en la máquina de desarrollo y la versión secundaria de la instalación de Python del cliente debe ser la misma que la versión secundaria de Python del clúster de Azure Databricks. 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. Ver las notas de la versión de Databricks Runtime versiones y compatibilidad.

    Nota:

    Si desea usar UDF de PySpark, es importante que la versión secundaria instalada de la máquina de desarrollo de Python coincida con la versión secundaria de Python que se incluye con Databricks Runtime instalado en el clúster.

  • La versión de los paquetes principal y secundario de Databricks Connect siempre debe coincidir con la versión de Databricks Runtime. Databricks recomienda usar siempre el paquete más reciente de Databricks Connect que coincida con la versión de Databricks Runtime. Por ejemplo, cuando se usa un clúster de Databricks Runtime 14.0, también debe usar la versión 14.0 del paquetedatabricks-connect.

    Nota:

    Consulte las notas de la versión de Databricks Connect para una lista de las actualizaciones de mantenimiento y las versiones disponibles de Databricks Connect.

    Usar el paquete más reciente de Databricks Connect que coincida con la versión de Databricks Runtime no es un requisito. Para Databricks Runtime 13.3 LTS y versiones posteriores, puede usar el paquete de Databricks Connect en todas las versiones de Databricks Runtime o superior a la versión del paquete de Databricks Connect. Sin embargo, si desea usar características que están disponibles en versiones posteriores de Databricks Runtime, debe actualizar el paquete de Databricks Connect en consecuencia.

  • 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. Esto puede ayudar a reducir o acortar la resolución de problemas técnicos relacionados. Consulte cómo activar un entorno virtual de Python para venv o Poetry en las secciones siguientes. Para obtener más información sobre estas herramientas, consulte venv o Poetry.

Activación de un entorno virtual de Python con venv

Si usa venv en la máquina de desarrollo y el clúster ejecuta Python 3.10, debe crear un entorno de venv con esa versión. El siguiente comando de ejemplo genera los scripts para activar un venv entorno con Python 3.10 y, a continuación, este comando coloca esos scripts en una carpeta oculta denominada .venv dentro del directorio de trabajo actual:

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

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

Para activar este venv entorno con estos scripts, consulte Funcionamiento de venvs.

Vaya directamente a Configuración del cliente.

Activación de un entorno virtual de Python con Poetry

  1. Instale Poetry, si aún no lo ha hecho.

  2. Si usa Poetry en la máquina de desarrollo y el clúster ejecuta Python 3.10, debe crear un entorno virtual de Poetry con esa versión. En el directorio raíz del proyecto de código de Python existente, indique a poetry inicializar el proyecto de código de Python para Poetry mediante la ejecución del siguiente comando:

    poetry init

  3. Poetry mostrará varias confirmaciones para que las complete. Ninguna de estas solicitudes es específica de Databricks Connect. Para obtener más información sobre estas confirmaciones, consulte init.

  4. Después de completar las confirmaciones, Poetry agrega un archivo pyproject.toml al proyecto de Python. Para obtener información sobre el archivo pyproject.toml, consulte El archivo pyproject.toml.

  5. En el directorio raíz del proyecto de código de Python, indique a poetry leer el archivo pyproject.toml, resolver las dependencias e instalarlas, crear un archivo de poetry.lock para bloquear las dependencias y, por último, crear un entorno virtual. Para ello, ejecute el siguiente comando:

    poetry install

  6. En el directorio raíz del proyecto de código de Python, indique a poetry que active el entorno virtual y escriba el shell. Para ello, ejecute el siguiente comando:

    poetry shell

Sabrá que el entorno virtual está activado y que el shell se ha escrito cuando el nombre del entorno virtual se muestra entre paréntesis justo antes de la solicitud del terminal, por ejemplo (my-project-py3.10).

Para desactivar el entorno virtual y salir del shell en cualquier momento, ejecute el comando exit.

Sabrá que ha salido del shell cuando el nombre del entorno virtual ya no se muestre entre paréntesis justo antes del símbolo del sistema del terminal.

Para obtener más información sobre cómo crear y administrar entornos virtuales de Poetry, consulte Administración de entornos.

Configuración del cliente

Sugerencia

Si ya tiene instalada la extensión de Databricks para Visual Studio Code, no es necesario seguir estas instrucciones de configuración.

La extensión de Databricks para Visual Studio Code ya cuenta con soporte técnico integrado de Databricks Connect para la versión Databricks Runtime 13.0 y posteriores. Consulte Depuración de código mediante Databricks Connect para la extensión de Databricks para Visual Studio Code.

Después de cumplir los requisitos de Databricks Connect, complete los pasos siguientes para configurar el cliente de Databricks Connect.

Paso 1: Instale el cliente de Databricks Connect

En estas secciones se describe cómo instalar el cliente de Databricks Connect con venv o Poetry.

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==14.0.*"  # 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 Paso 2: 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@~14.0  # Or X.Y to match your cluster version.

    Nota:

    Databricks recomienda usar la “notación at-tilde” para especificar databricks-connect@~14.0 en lugar de databricks-connect==14.0, 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.

Paso 2: Configuración de las propiedades de conexión

En esta sección, configurará las propiedades para establecer una conexión entre Databricks Connect y el clúster remoto de Azure Databricks. Estas propiedades incluyen la configuración para autenticar Databricks Connect con el clúster.

Para Databricks Connect para Databricks Runtime 13.1 y versiones posteriores, Databricks Connect incluye el SDK de Databricks para Python. Este SDK implementa el estándar de autenticación unificada del cliente de Databricks, un enfoque arquitectónico y programático consolidado y coherente para la autenticación. Este enfoque configura y automatiza la autenticación con Azure Databricks de manera más centralizada y predecible. Permite configurar la autenticación de Azure Databricks una vez y, a continuación, usar esa configuración en varias herramientas y SDK de Azure Databricks sin cambios adicionales en la configuración de autenticación.

Nota:

  1. Recopile las propiedades de configuración siguientes.

  2. Configure la conexión dentro del código. Databricks Connect busca propiedades de configuración en el orden siguiente hasta que las encuentre. Luego, deja de buscar en el resto de opciones. Los detalles de cada opción aparecen después de la tabla siguiente:

    Opción de propiedades de configuración Se aplica a
    1. El método remote() de la clase DatabricksSession Solo la autenticación de token de acceso personal de Azure Databricks
    2. Un perfil de configuración de Azure Databricks Todos los tipos de autenticación de Azure Databricks
    3. La variable de entorno SPARK_REMOTE Solo la autenticación de token de acceso personal de Azure Databricks
    4. La variable de entorno DATABRICKS_CONFIG_PROFILE Todos los tipos de autenticación de Azure Databricks
    5. Una variable de entorno para cada propiedad de conexión Todos los tipos de autenticación de Azure Databricks
    6. Un perfil de configuración de Azure Databricks denominado DEFAULT Todos los tipos de autenticación de Azure Databricks

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

      Databricks no recomienda especificar directamente estas propiedades de conexión en el código. En su lugar, 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()

# 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 perfil de configuración de Azure 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()

    3. Variable de entorno SPARK_REMOTE

      Para esta opción, que se aplica solo a la autenticación de token de acceso personal de Azure Databricks, establece la variable de entorno SPARK_REMOTE en la siguiente cadena, reemplazando los marcadores de posición con los valores adecuados.

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

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

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Para establecer las variables de entorno, consulte la documentación del sistema operativo.

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

      Para establecer las variables de entorno, consulte la documentación del sistema operativo.

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

      Para establecer las variables de entorno, consulte la documentación del sistema operativo.

    6. Perfil de configuración de Azure 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()

  3. Validar el entorno y la conexión al clúster de Databricks

    • El comando siguiente comprobará que el entorno, las credenciales predeterminadas y la conexión al clúster están configurados correctamente para Databricks Connect.

      databricks-connect test

      Este comando recoge las credenciales predeterminadas configuradas en el entorno (como el perfil de configuración de DEFAULT o a través de variables de entorno).

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

    • Además, también puede usar el shell de pyspark que se incluye como parte de Databricks Connect para Python. Inicie el shell mediante la ejecución de:

      pyspark

      Aparece el shell de Spark, por ejemplo:

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

      En la solicitud de >>>, ejecute un sencillo comando PySpark, como spark.range(1,10).show(). Si no hay errores, se ha conectado correctamente.

      Si se ha conectado correctamente, para detener el shell de Spark, presione Ctrl + d o Ctrl + z, o ejecute el comando quit() o exit().

      Para más detalles sobre el databricks-connect binario, consulte uso avanzado de Databricks Connect para Python