Instale o Databricks Connect para Python

Observação

Este artigo abrange Databricks Connect para Databricks Runtime 13.3 LTS e acima.

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

Requisitos

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

• Se o senhor estiver se conectando a serverless computeseu workspace deve atender aos requisitos de serverless compute .

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

• O senhor 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 da tabela abaixo.

  Versão do Databricks Connect	Tipo de Compute	Versão compatível do Python
  15.3	Cluster	3.11
  15.2	Cluster	3.11
  15.1	Cluster	3.11
  15.1	Serverless	3.10
  13.3 LTS para 14.3 LTS	Cluster	3.10

• Se o senhor quiser usar os UDFs do PySpark, a versão secundária instalada no computador de desenvolvimento do Python deve corresponder à versão secundária do Python que está incluída no Databricks Runtime instalado no cluster ou serverless compute. Para encontrar a versão secundária Python do seu cluster, consulte a seção Ambiente do sistema do Databricks Runtime notas sobre a versão do seu cluster ou serverless compute. Consulte Databricks Runtime notas sobre a versão versões e compatibilidade e serverless compute notas sobre a versão.

Ativar um ambiente virtual Python

A Databricks recomenda enfaticamente que o senhor tenha um ambiente virtual Python ativado para cada versão do Python que usar com o Databricks Connect. Os ambientes virtuais Python ajudam a garantir que o senhor 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 o site ou Poetry.

Instalar o cliente Databricks Connect

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

Observação

Se o senhor já tiver a extensão Databricks para o Visual Studio Code instalada, não precisará seguir estas instruções de configuração, pois a extensão Databricks para o Visual Studio Code já tem suporte integrado para Databricks Connect para Databricks Runtime 13.3 LTS e acima. Pule para Depurar código usando o 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, caso já esteja instalado, executando o comando uninstall . Isso é necessário porque o pacote databricks-connect entra em conflito com o PySpark. Para obter detalhes, consulte Instalações conflitantes do PySpark. Para verificar se o PySpark já está instalado, execute o comando show .

   # 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 comando install . Use a opção --upgrade para fazer upgrade de qualquer instalação de cliente existente para a versão especificada.

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

   Observação

   A 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, ajuda a garantir que você possa usar o recurso compatível mais recente para esses clusters.

Avance para Configurar propriedades de conexão.

Instale o cliente Databricks Connect com Poetry

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

   # 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 comando add .

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

   Observação

   A Databricks recomenda que você use a notação “at-tilde” para especificar databricks-connect@~14.3 em vez de databricks-connect==14.3, para garantir que o pacote mais recente esteja instalado. Embora isso não seja um requisito, ajuda a garantir que você possa usar o recurso compatível mais recente para esses clusters.

Configurar as propriedades da conexão

Nesta seção, configure as propriedades para estabelecer uma conexão entre o Databricks Connect e o seu Databricks cluster ou serverless computeque inclui o seguinte:

• O nome da instância do espaço de trabalho do Databricks. Esse é o valor do Server hostname para seu computador. Consulte Obter detalhes da conexão para um recurso de computação do Databricks.

• Quaisquer outras propriedades que sejam necessárias para o tipo de autenticação do Databricks que o senhor deseja usar.

Observação

• Para a autenticação OAuth de usuário para máquina (U2M), o senhor deve usar a CLI da Databricks para se autenticar antes de executar o código Python. Veja o tutorial.

Configurar uma conexão com um cluster

Para configurar uma conexão com um cluster, o senhor precisará do ID do seu cluster. O senhor pode obter o ID do cluster no URL. Consulte URL e ID do cluster.

O senhor pode configurar a conexão com seu cluster de uma das seguintes maneiras. O Databricks Connect procura as propriedades de configuração na seguinte ordem e usa a primeira configuração que encontrar. Para obter informações sobre configurações avançadas, consulte Uso avançado do Databricks Connect para 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 Databricks chamado default

O método remote() da classe DatabricksSession

Para esta opção, que se aplica apenas à autenticação access token pessoal do Databricks , especifique o nome da instância workspace , o access token pessoal do Databricks e a ID dos clusters.

Você pode inicializar a classe DatabricksSession de diversas maneiras, como a seguir:

• Defina os campos host, token e cluster_id em DatabricksSession.builder.remote().

• Use a classe Config do SDK do Databricks.

• Especifique um perfil de configuração do Databricks junto com o campo cluster_id .

• Defina as strings de conexão do Spark Connect em DatabricksSession.builder.remote().

Em vez de especificar essas propriedades de conexão no código, o site Databricks recomenda configurar as propriedades por meio de variáveis de ambiente ou arquivos de configuração, conforme descrito ao longo desta seção. Os exemplos de código a seguir pressupõem que o senhor forneça alguma implementação das funções retrieve_* propostas para obter as propriedades necessárias do usuário ou de algum outro armazenamento de configuração, como o AWS Systems Manager Parameter Store.

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 esta opção, crie ou identifique um perfil de configuração do Databricks contendo o campo cluster_id e quaisquer outros campos necessários para o tipo de autenticação do Databricks que você deseja usar.

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

• Para autenticação access token pessoal do Databricks: host e token.

• Para autenticação OAuth máquina a máquina (M2M) (quando compatível): host, client_id e client_secret.

• Para autenticação usuário-máquina (U2M) OAuth (quando compatível): host.

Observação

A autenticação básica usando um nome de usuário e senha da Databricks chegou ao fim da vida útil em 10 de julho de 2024. Consulte End of life para Databricks-gerenciar senhas.

Em seguida, defina o nome desse perfil de configuração por meio da classe Config .

Observação

O senhor pode usar a opção --configure-cluster do comando auth login para adicionar automaticamente o campo cluster_id a um perfil de configuração novo ou existente. Para obter mais informações, execute o comando databricks auth login -h.

Você pode especificar cluster_id de algumas maneiras, como segue:

• Inclua o campo cluster_id em seu perfil de configuração e especifique apenas o nome do perfil de configuração.

• Especifique o nome do perfil de configuração junto com o campo cluster_id .

Se você já configurou a variável de ambiente DATABRICKS_CLUSTER_ID com o ID dos clusters , também não será necessário 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 variável de ambiente DATABRICKS_CONFIG_PROFILE

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

Se você já configurou a variável de ambiente DATABRICKS_CLUSTER_ID com o ID dos clusters , também não será necessário especificar cluster_id.

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

• Para autenticação access token pessoal do Databricks: host e token.

• Para autenticação OAuth máquina a máquina (M2M) (quando compatível): host, client_id e client_secret.

• Para autenticação usuário-máquina (U2M) OAuth (quando compatível): host.

Observação

A autenticação básica usando um nome de usuário e senha da Databricks chegou ao fim da vida útil em 10 de julho de 2024. Consulte End of life para Databricks-gerenciar senhas.

Observação

Você pode usar o comando --configure-cluster do auth login para adicionar automaticamente o campo cluster_id a um perfil de configuração novo ou existente. Para mais informações, execute o comando databricks auth login -h.

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

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

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

Para esta opção, defina a variável de ambiente DATABRICKS_CLUSTER_ID e quaisquer outras variáveis de ambiente necessárias para o tipo de autenticação do 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 access token pessoal do Databricks: DATABRICKS_HOST e DATABRICKS_TOKEN.

• Para autenticação OAuth máquina a máquina (M2M): DATABRICKS_HOST, DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET.

• Para autenticação usuário-máquina (U2M) OAuth: DATABRICKS_HOST.

Observação

A autenticação básica usando um nome de usuário e senha da Databricks chegou ao fim da vida útil em 10 de julho de 2024. Consulte End of life para Databricks-gerenciar senhas.

Em seguida, inicialize a classe DatabricksSession da seguinte maneira:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Um perfil de configuração do Databricks chamado DEFAULT

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

Se você já configurou a variável de ambiente DATABRICKS_CLUSTER_ID com o ID dos clusters , também não será necessário especificar cluster_id.

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

• Para autenticação access token pessoal do Databricks: host e token.

• Para autenticação OAuth máquina a máquina (M2M) (quando compatível): host, client_id e client_secret.

• Para autenticação usuário-máquina (U2M) OAuth (quando compatível): host.

Observação

A autenticação básica usando um nome de usuário e senha da Databricks chegou ao fim da vida útil em 10 de julho de 2024. Consulte End of life para Databricks-gerenciar senhas.

Nomeie esse perfil de configuração DEFAULT.

Observação

O senhor pode usar a opção --configure-cluster do comando auth login para adicionar automaticamente o campo cluster_id ao perfil de configuração DEFAULT. Para obter mais informações, execute o comando databricks auth login -h.

Em seguida, inicialize a classe DatabricksSession da seguinte maneira:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

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

Prévia

Este recurso está em visualização pública.

Databricks Connect suporta a conexão com serverless compute. Para usar esse recurso, é necessário atender aos requisitos de conexão com o serverless. Veja os requisitos.

Importante

Esse recurso tem as seguintes limitações:

• Todas as limitações do Databricks Connect for Python

• Todas as limitações da computação sem servidor

• Somente as dependências Python incluídas como parte do ambiente serverless compute podem ser usadas para UDFs. Consulte Ambiente do sistema. Não é possível instalar dependências adicionais.

• Não há suporte para UDFs com módulos personalizados.

O senhor pode configurar uma conexão com serverless compute de uma das seguintes maneiras:

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

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

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

• Como alternativa, basta atualizar o código do Databricks Connect Python da seguinte forma:

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

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

Observação

A sessão serverless compute é encerrada após 10 minutos de inatividade. Depois disso, o processo Python precisa ser reiniciado no lado do cliente para criar uma nova sessão Spark para se conectar a serverless compute.

Validar a conexão com o Databricks

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

databricks-connect test

Como alternativa, o senhor pode usar o pyspark shell que está incluído como parte do Databricks Connect para Python e executar um comando simples. Para obter mais detalhes sobre o site PySpark shell, consulte PySpark shell.