Partilhar via

Instalar o Databricks Connect para Python

  • Artigo

Nota

Este artigo aborda o Databricks Connect for Databricks Runtime 13.3 LTS e superior.

Este artigo descreve como instalar o Databricks Connect for Python. Consulte O que é Databricks Connect?. Para a versão Scala deste artigo, consulte Instalar o Databricks Connect for Scala.

Requisitos

Para instalar o Databricks Connect for Python, os seguintes requisitos devem ser atendidos:

  • Se você estiver se conectando à computação sem servidor, seu espaço de trabalho deverá atender aos requisitos de computação sem servidor.

    Nota

    A computação sem servidor é suportada no Databricks Connect versão 15.1 e superior. Além disso, as versões do Databricks Connect iguais ou inferiores à versão Databricks Runtime no serverless são totalmente compatíveis. Consulte Notas de versão. Para verificar se a versão do Databricks Connect é compatível com computação sem servidor, consulte Validar a conexão com o Databricks.

  • Se você estiver se conectando a um cluster, o cluster de destino deverá atender aos requisitos de configuração do cluster, que incluem os requisitos de versão do Databricks Runtime.

  • Você deve ter o Python 3 instalado em sua máquina de desenvolvimento, e a versão secundária do Python instalada em sua máquina de desenvolvimento deve atender aos requisitos de versão na tabela abaixo.

    Tipo de computação Versão do Databricks Connect Versão Python compatível
    Sem servidor 15.1 e superior 3.11
    Cluster 15.1 e superior 3.11
    Cluster 13,3 LTS a 14,3 LTS 3,10

  • Se você quiser usar UDFs do PySpark, a versão secundária do Python instalada na sua máquina de desenvolvimento deve corresponder à versão secundária do Python incluída no Databricks Runtime instalado no cluster ou na computação sem servidor. Para encontrar a versão secundária do Python do cluster, consulte a seção Ambiente do sistema das notas de versão do Databricks Runtime para seu cluster ou computação sem servidor. Consulte Notas de versão, versões e compatibilidade do Databricks Runtime e Notas de versão de computação sem servidor.

Ativar um ambiente virtual Python

O Databricks recomenda que você tenha um ambiente virtual Python ativado para cada versão do Python que você usa com o Databricks Connect. Os ambientes virtuais Python ajudam a garantir que você esteja usando as versões corretas do Python e do Databricks Connect juntos. Para obter mais informações sobre essas ferramentas e como ativá-las, consulte venv ou Poetry.

Instalar o cliente Databricks Connect

Esta seção descreve como instalar o cliente Databricks Connect com venv ou Poetry.

Nota

Se você já tiver a extensão Databricks para Visual Studio Code instalada, não precisará seguir estas instruções de instalação, porque a extensão Databricks para Visual Studio Code já tem suporte interno para Databricks Connect for Databricks Runtime 13.3 LTS e superior. Pule para Depurar código usando Databricks Connect para a extensão Databricks para Visual Studio Code.

Instale o cliente Databricks Connect com venv

  1. Com seu ambiente virtual ativado, desinstale o PySpark, se ele já estiver instalado, executando o uninstall comando. Isso é necessário porque o pacote entra em conflito com o databricks-connect PySpark. Para obter detalhes, consulte Instalações conflitantes do PySpark. Para verificar se o PySpark já está instalado, execute o show comando.

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Com seu ambiente virtual ainda ativado, instale o cliente Databricks Connect executando o install comando. Use a --upgrade opção para atualizar qualquer instalação de cliente existente para a versão especificada.

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

    Nota

    O Databricks recomenda que você anexe a notação "ponto-asterisco" para especificar databricks-connect==X.Y.* em vez de databricks-connect=X.Y, para garantir que o pacote mais recente esteja instalado. Embora isso não seja um requisito, ele ajuda a garantir que você possa usar os recursos suportados mais recentes para esse cluster.

Pule para Configurar propriedades de conexão.

Instale o cliente Databricks Connect com o Poetry

  1. Com seu ambiente virtual ativado, desinstale o PySpark, se ele já estiver instalado, executando o remove comando. Isso é necessário porque o pacote entra em conflito com o databricks-connect PySpark. Para obter detalhes, consulte Instalações conflitantes do PySpark. Para verificar se o PySpark já está instalado, execute o show comando.

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Com seu ambiente virtual ainda ativado, instale o cliente Databricks Connect executando o add comando.

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

    Nota

    O Databricks recomenda que você use a notação "at-tilde" para especificar databricks-connect@~15.4 em vez de databricks-connect==15.4, para garantir que o pacote mais recente esteja instalado. Embora isso não seja um requisito, ele ajuda a garantir que você possa usar os recursos suportados mais recentes para esse cluster.

Configurar propriedades de conexão

Nesta seção, você configura propriedades para estabelecer uma conexão entre o Databricks Connect e seu cluster do Azure Databricks ou computação sem servidor, que inclui o seguinte:

Nota

  • A autenticação OAuth user-to-machine (U2M) é suportada no Databricks SDK para Python 0.19.0 e superior. Talvez seja necessário atualizar a versão instalada do seu projeto de código do Databricks SDK for Python para 0.19.0 ou superior para usar a autenticação OAuth U2M. Consulte Introdução ao SDK do Databricks para Python.

    Para autenticação OAuth U2M, você deve usar a CLI do Databricks para autenticar antes de executar o código Python. Consulte o Tutorial.

  • Autenticação OAuth máquina-a-máquina (M2M) A autenticação OAuth máquina-a-máquina (M2M) é suportada no Databricks SDK para Python 0.18.0 e superior. Talvez seja necessário atualizar a versão instalada do seu projeto de código do Databricks SDK for Python para 0.18.0 ou superior para usar a autenticação OAuth M2M. Consulte Introdução ao SDK do Databricks para Python.

  • O SDK do Databricks para Python ainda não implementou a autenticação de identidades gerenciadas do Azure.

Configurar uma conexão com um cluster

Para configurar uma conexão com um cluster, você precisará da ID do cluster. Você pode obter o ID do cluster a partir da URL. Consulte URL e ID do cluster.

Você pode configurar a conexão com seu cluster de uma das seguintes maneiras. O Databricks Connect procura propriedades de configuração na seguinte ordem e usa a primeira configuração encontrada. Para obter informações de configuração avançada, consulte Uso avançado do Databricks Connect for Python.

  1. O método remote() da classe DatabricksSession.
  2. Um perfil de configuração do Databricks
  3. A variável de ambiente DATABRICKS_CONFIG_PROFILE
  4. Uma variável de ambiente para cada propriedade de configuração
  5. Um perfil de configuração do Databricks chamado DEFAULT

O DatabricksSession método da remote() classe

Para esta opção, que se aplica apenas à autenticação do token de acesso pessoal do Azure Databricks, especifique o nome da instância do espaço de trabalho, o token de acesso pessoal do Azure Databricks e a ID do cluster.

Você pode inicializar a classe de DatabricksSession várias maneiras, da seguinte maneira:

  • Defina os hostcampos DatabricksSession.builder.remote(), tokene em cluster_id .
  • Use a classe do SDK do Databricks Config .
  • Especifique um perfil de configuração do Databricks junto com o cluster_id campo.
  • Defina a cadeia de conexão Spark Connect em DatabricksSession.builder.remote().

Em vez de especificar essas propriedades de conexão em seu código, o Databricks recomenda configurar propriedades por meio de variáveis de ambiente ou arquivos de configuração, conforme descrito nesta seção. Os exemplos de código a seguir pressupõem que você forneça alguma implementação das funções propostas retrieve_* para obter as propriedades necessárias do usuário ou de algum outro repositório de configuração, como o Azure KeyVault.

O código para cada uma dessas abordagens é o seguinte:

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

Um perfil de configuração do Databricks

Para essa opção, crie ou identifique um perfil de configuração do Azure Databricks contendo o campo cluster_id e quaisquer outros campos necessários para o tipo de autenticação Databricks que você deseja usar.

Os campos de perfil de configuração necessários para cada tipo de autenticação são os seguintes:

  • Para autenticação de token de acesso pessoal do Azure Databricks: host e token.
  • Para autenticação OAuth máquina-a-máquina (M2M) (quando suportado): host, client_ide client_secret.
  • Para autenticação OAuth user-to-machine (U2M) (quando suportado): host.
  • Para a autenticação da entidade de serviço do Microsoft Entra ID (anteriormente Azure Ative Directory): host, azure_tenant_id, azure_client_id, azure_client_secrete possivelmente azure_workspace_resource_id.
  • Para autenticação da CLI do Azure: host.
  • Para autenticação de identidades gerenciadas do Azure (quando suportado): host, azure_use_msi, azure_client_ide possivelmente azure_workspace_resource_id.

Em seguida, defina o nome desse perfil de configuração através da Config classe.

Você pode especificar cluster_id de algumas maneiras, da seguinte maneira:

  • Inclua o cluster_id campo no seu perfil de configuração e, em seguida, especifique apenas o nome do perfil de configuração.
  • Especifique o nome do perfil de configuração juntamente com o cluster_id campo.

Se você já tiver definido a DATABRICKS_CLUSTER_ID variável de ambiente com a ID do cluster, também não precisará especificar cluster_id.

O código para cada uma dessas abordagens é o seguinte:

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

A DATABRICKS_CONFIG_PROFILE variável de ambiente

Para essa opção, crie ou identifique um perfil de configuração do Azure Databricks contendo o campo cluster_id e quaisquer outros campos necessários para o tipo de autenticação Databricks que você deseja usar.

Se você já tiver definido a DATABRICKS_CLUSTER_ID variável de ambiente com a ID do cluster, também não precisará especificar cluster_id.

Os campos de perfil de configuração necessários para cada tipo de autenticação são os seguintes:

  • Para autenticação de token de acesso pessoal do Azure Databricks: host e token.
  • Para autenticação OAuth máquina-a-máquina (M2M) (quando suportado): host, client_ide client_secret.
  • Para autenticação OAuth user-to-machine (U2M) (quando suportado): host.
  • Para a autenticação da entidade de serviço do Microsoft Entra ID (anteriormente Azure Ative Directory): host, azure_tenant_id, azure_client_id, azure_client_secrete possivelmente azure_workspace_resource_id.
  • Para autenticação da CLI do Azure: host.
  • Para autenticação de identidades gerenciadas do Azure (quando suportado): host, azure_use_msi, azure_client_ide possivelmente azure_workspace_resource_id.

Defina a DATABRICKS_CONFIG_PROFILE variável de ambiente como o nome desse perfil de configuração. Em seguida, inicialize a DatabricksSession classe da seguinte maneira:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Uma variável de ambiente para cada propriedade de configuração

Para essa opção, defina a DATABRICKS_CLUSTER_ID variável de ambiente e quaisquer outras variáveis de ambiente necessárias para o tipo de autenticação Databricks que você deseja usar.

As variáveis de ambiente necessárias para cada tipo de autenticação são as seguintes:

  • Para autenticação de token de acesso pessoal do Azure Databricks: DATABRICKS_HOST e DATABRICKS_TOKEN.
  • Para autenticação OAuth máquina-a-máquina (M2M) (quando suportado): DATABRICKS_HOST, DATABRICKS_CLIENT_IDe DATABRICKS_CLIENT_SECRET.
  • Para autenticação OAuth user-to-machine (U2M) (quando suportado): DATABRICKS_HOST.
  • Para a autenticação da entidade de serviço do Microsoft Entra ID (anteriormente Azure Ative Directory): DATABRICKS_HOST, ARM_TENANT_ID, ARM_CLIENT_ID, ARM_CLIENT_SECRETe possivelmente DATABRICKS_AZURE_RESOURCE_ID.
  • Para autenticação da CLI do Azure: DATABRICKS_HOST.
  • Para autenticação de identidades gerenciadas do Azure (quando suportado): DATABRICKS_HOST, ARM_USE_MSI, ARM_CLIENT_IDe possivelmente DATABRICKS_AZURE_RESOURCE_ID.

Em seguida, inicialize a DatabricksSession classe da seguinte maneira:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Um perfil de configuração do Databricks chamado DEFAULT

Para essa opção, crie ou identifique um perfil de configuração do Azure Databricks contendo o campo cluster_id e quaisquer outros campos necessários para o tipo de autenticação Databricks que você deseja usar.

Se você já tiver definido a DATABRICKS_CLUSTER_ID variável de ambiente com a ID do cluster, também não precisará especificar cluster_id.

Os campos de perfil de configuração necessários para cada tipo de autenticação são os seguintes:

  • Para autenticação de token de acesso pessoal do Azure Databricks: host e token.
  • Para autenticação OAuth máquina-a-máquina (M2M) (quando suportado): host, client_ide client_secret.
  • Para autenticação OAuth user-to-machine (U2M) (quando suportado): host.
  • Para a autenticação da entidade de serviço do Microsoft Entra ID (anteriormente Azure Ative Directory): host, azure_tenant_id, azure_client_id, azure_client_secrete possivelmente azure_workspace_resource_id.
  • Para autenticação da CLI do Azure: host.
  • Para autenticação de identidades gerenciadas do Azure (quando suportado): host, azure_use_msi, azure_client_ide possivelmente azure_workspace_resource_id.

Nomeie este perfil DEFAULTde configuração .

Em seguida, inicialize a DatabricksSession classe da seguinte maneira:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Configurar uma conexão com computação sem servidor

Importante

Esta funcionalidade está em Pré-visualização Pública.

O Databricks Connect suporta a conexão com computação sem servidor. Para usar esse recurso, os requisitos para se conectar ao serverless devem ser atendidos. Consulte Requisitos.

Importante

Este recurso tem as seguintes limitações:

  • Todas as limitações do Databricks Connect for Python
  • Todas as limitações de computação sem servidor
  • Somente dependências Python incluídas como parte do ambiente de computação sem servidor podem ser usadas para UDFs. Para obter informações sobre o ambiente do sistema, consulte a documentação da imagem do cliente que você está usando. Consulte Imagens de cliente sem servidor. Não é possível instalar dependências adicionais.
  • UDFs com módulos personalizados não são suportados.

Você pode configurar uma conexão com computação sem servidor de uma das seguintes maneiras:

  • Defina a variável DATABRICKS_SERVERLESS_COMPUTE_ID de ambiente local como auto. Se essa variável de ambiente estiver definida, o Databricks Connect ignorará o cluster_id.

  • Em um perfil de configuração local do Databricks, defina serverless_compute_id = autoe, em seguida, faça referência a esse perfil a partir do seu código do Databricks Connect Python.

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

  • Como alternativa, basta atualizar seu código Databricks Connect Python da seguinte maneira:

    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

A sessão de computação sem servidor expira após 10 minutos de inatividade. Depois disso, uma nova sessão do Spark deve ser criada para se conectar à computação sem servidor. Isso pode ser feito com spark = DatabricksSession.builder.serverless(True).getOrCreate().

Validar a conexão com o Databricks

Para validar seu ambiente, as credenciais padrão e a conexão com a computação estão configuradas corretamente para o Databricks Connect, execute o databricks-connect test comando, que falha com um código de saída diferente de zero e uma mensagem de erro correspondente quando deteta qualquer incompatibilidade na configuração.

databricks-connect test

Você também pode validar seu ambiente em seu código Python usando validateSession():

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