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 .
Observação
O compute sem servidor é compatível com o Databricks Connect versão 15.1 e o acima. Além disso, as versões do Databricks Connect iguais ou inferiores à versão do Databricks Runtime em serverless são totalmente compatíveis. Veja as notas sobre a versão. Para verificar se a versão Databricks Connect é compatível com serverless compute, consulte Validar a conexão com Databricks.
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.
Tipo de Compute
Versão do Databricks Connect
Versão compatível do Python
Serverless
15.1 e acima
3.11
Cluster
15.1 e acima
3.11
Cluster
13.3 LTS para 14.3 LTS
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 Visual Studio Code instalada, não precisará seguir estas instruções de configuração, pois a extensão Databricks para 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
Com seu ambiente virtual ativado, desinstale o PySpark, caso já esteja instalado, executando o comando
uninstall
. Isso é necessário porque o pacotedatabricks-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 comandoshow
.# Is PySpark already installed? pip3 show pyspark # Uninstall PySpark pip3 uninstall pyspark
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==15.4.*" # 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 dedatabricks-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
Com seu ambiente virtual ativado, desinstale o PySpark, caso já esteja instalado, executando o comando
remove
. Isso é necessário porque o pacotedatabricks-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 comandoshow
.# Is PySpark already installed? poetry show pyspark # Uninstall PySpark poetry remove pyspark
Com seu ambiente virtual ainda ativado, instale o cliente Databricks Connect executando o comando
add
.poetry add databricks-connect@~15.4 # 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@~15.4
em vez dedatabricks-connect==15.4
, 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 nome do host do servidor para o seu compute. 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.
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
ecluster_id
emDatabricksSession.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 essa opção, crie ou identifique um perfil de configuração do Databricks que contenha o campo cluster_id
e quaisquer outros campos necessários para o tipo de autenticação do Databricks que o senhor 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
etoken
.Para autenticação OAuth máquina a máquina (M2M) (quando compatível):
host
,client_id
eclient_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 essa opção, crie ou identifique um perfil de configuração do Databricks que contenha o campo cluster_id
e quaisquer outros campos necessários para o tipo de autenticação do Databricks que o senhor 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
etoken
.Para autenticação OAuth máquina a máquina (M2M) (quando compatível):
host
,client_id
eclient_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
eDATABRICKS_TOKEN
.Para autenticação OAuth máquina a máquina (M2M):
DATABRICKS_HOST
,DATABRICKS_CLIENT_ID
eDATABRICKS_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 essa opção, crie ou identifique um perfil de configuração do Databricks que contenha o campo cluster_id
e quaisquer outros campos necessários para o tipo de autenticação do Databricks que o senhor 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
etoken
.Para autenticação OAuth máquina a máquina (M2M) (quando compatível):
host
,client_id
eclient_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:
Somente as dependências Python incluídas como parte do ambiente serverless compute podem ser usadas para UDFs. Para obter informações sobre o ambiente do sistema, view a documentação da imagem do cliente que o senhor está usando. Consulte Imagens de cliente sem servidor. Dependências adicionais não podem ser instaladas.
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
comoauto
. Se essa variável de ambiente for definida, o Databricks Connect ignorará ocluster_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 as SparkSession spark = DatabricksSession.builder.serverless(True).getOrCreate()
from databricks.connect import DatabricksSession as SparkSession spark DatabricksSession.builder.remote(serverless=True).getOrCreate()
Observação
A sessão serverless compute é encerrada após 10 minutos de inatividade. Depois disso, uma nova sessão Spark deve ser criada para se conectar a serverless compute. Isso pode ser feito com spark = DatabricksSession.builder.serverless(True).getOrCreate()
.
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
O senhor também pode validar seu ambiente no código Python usando validateSession()
:
DatabricksSession.builder.validateSession(True).getOrCreate()