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
Cluster
13.3 LTS para 14.3 LTS
3.10
Cluster
15.1 e acima
3.11
Serverless
15.1 e acima
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==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 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@~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 dedatabricks-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 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
A autenticação OAuth de usuário para máquina (U2M) e a autenticação OAuth de máquina para máquina (M2M) são compatíveis com o SDK da Databricks para Python 0.19.0 e acima. Talvez seja necessário atualizar a versão instalada do SDK da Databricks para Python no seu projeto de código para 0.19.0 ou acima para usar a autenticação OAuth U2M ou M2M. Consulte Começar a usar o Databricks SDK para Python.
Para a autenticação OAuth U2M, o senhor deve usar a CLI da Databricks para se autenticar antes de executar o código Python. Veja o tutorial.
A autenticação de credenciais do Google Cloud s e a autenticação de ID do Google Clouds são compatíveis com o Databricks SDK for Python 0.14.0 e superiores. Talvez seja necessário atualizar a versão instalada do SDK da Databricks para Python no seu projeto de código para 0.14.0 ou acima para usar a autenticação de credenciais do Google Clouds ou a autenticação de ID. Consulte Começar a usar o Databricks SDK para Python.
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 Google Cloud Secret Manager.
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
.Para autenticação de credenciais do Google clouds (quando compatível):
host
egoogle_credentials
.Para autenticação de ID do Google clouds (quando compatível):
host
egoogle_service_acccount
.
Em seguida, defina o nome desse perfil de configuração por meio da classe Config
.
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
.Para autenticação de credenciais do Google clouds (quando compatível):
host
egoogle_credentials
.Para autenticação de ID do Google clouds (quando compatível):
host
egoogle_service_acccount
.
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) (quando compatível):
DATABRICKS_HOST
,DATABRICKS_CLIENT_ID
,DATABRICKS_CLIENT_SECRET
.Para autenticação usuário-máquina (U2M) OAuth (quando compatível):
DATABRICKS_HOST
.Para autenticação de credenciais do Google clouds (quando compatível):
DATABRICKS_HOST
eGOOGLE_CREDENTIALS
.Para autenticação de ID do Google clouds (quando compatível):
DATABRICKS_HOST
eGOOGLE_SERVICE_ACCOUNT
.
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
.Para autenticação de credenciais do Google clouds (quando compatível):
host
egoogle_credentials
.Para autenticação de ID do Google clouds (quando compatível):
host
egoogle_service_acccount
.
Nomeie esse perfil de configuração DEFAULT
.
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. 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
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, 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
O senhor também pode validar seu ambiente no código Python usando validateSession()
:
DatabricksSession.builder.validateSession(True).getOrCreate()