Instalar o Databricks Connect para Python
Observação
Esse artigo aborda o Databricks Connect para Databricks Runtime 13.3 LTS e superior.
Esse artigo descreve como instalar o Databricks Connect para Python. Consulte O que é o Databricks Connect?. Para obter a versão para Scala deste artigo, consulte Instalar o Databricks Connect para Scala.
Requisitos
Para instalar o Databricks Connect para Python, os seguintes requisitos devem ser atendidos:
Se você estiver se conectando à computação sem servidor, seu workspace deverá atender aos requisitos para computação sem servidor.
Se você estiver se conectando a um cluster, seu cluster de destino deverá atender aos requisitos de configuração do cluster, que inclui os requisitos de versão do Databricks Runtime.
Você deve ter o Python 3 instalado em seu computador de desenvolvimento e a versão secundária do Python instalada em seu computador deve atender aos requisitos de versão na tabela abaixo.
Versão do Databricks Connect Tipo de computação Versão compatível do Python 15.1 Cluster 3.11 15.1 Sem servidor 3.10 13.3 LTS a 14.3 LTS Cluster 3.10 Se você quiser usar UDFs do PySpark, a versão secundária do Python instalada no computador de desenvolvimento deve corresponder à versão secundária do Python incluída no Databricks Runtime instalado no cluster ou computação sem servidor. Para localizar a versão secundária do Python do seu cluster, consulte a seção Ambiente do sistema das notas sobre a versão do Databricks Runtime para seu cluster ou computação sem servidor. Consulte Versões e compatibilidade das notas sobre a versão do Databricks Runtime e Notas sobre a versão da computação sem servidor.
Ativar um ambiente virtual do 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 o uso das versões corretas do Python e do Databricks Connect em conjunto. Para obter mais informações sobre essas ferramentas e como ativá-las, consulte venv ou Poetry.
Instalar o cliente do Databricks Connect
Esta seção descreve como instalar o cliente do Databricks Connect com venv ou Poetry.
Observação
Se você já tiver a extensão do Databricks para o Visual Studio Code instalada, não precisará seguir essas instruções de instalação, pois a extensão do Databricks para Visual Studio Code já tem suporte interno para Databricks Connect para Databricks Runtime 13.3 LTS e superior. Pule para Depurar código usando o Databricks Connect para a extensão do Databricks para Visual Studio Code.
Instale o cliente do Databricks Connect com venv
Com o ambiente virtual ativado, desinstale o PySpark, se ele já estiver instalado, executando o comando
uninstall
. Isso é necessário porque o pacotedatabricks-connect
está em conflito com o PySpark. Para obter detalhes, confira 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 o ambiente virtual ainda ativado, instale o cliente do Databricks Connect executando o comando
install
. Use a opção--upgrade
para atualizar qualquer instalação do cliente existente para a versão especificada.pip3 install --upgrade "databricks-connect==14.3.*" # Or X.Y.* to match your cluster version.
Observação
O Databricks recomenda que você acrescente a notação "dot-asterisk" a ser especificada
databricks-connect==X.Y.*
em vez dedatabricks-connect=X.Y
, para garantir que o pacote mais recente esteja instalado. Embora não seja um requisito, isso ajudará a garantir que você possa usar os recursos mais recentes com suporte para esse cluster.
Pule para Configurar as propriedades da conexão.
Instale o cliente do Databricks Connect com Poesia
Com o ambiente virtual ativado, desinstale o PySpark, se ele já estiver instalado, executando o comando
remove
. Isso é necessário porque o pacotedatabricks-connect
está em conflito com o PySpark. Para obter detalhes, confira 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 o ambiente virtual ainda ativado, instale o cliente do Databricks Connect executando o comando
add
.poetry add databricks-connect@~14.3 # Or X.Y to match your cluster version.
Observação
O Databricks recomenda que você use a notação "at-tilde" a ser especificada
databricks-connect@~14.3
em vez dedatabricks-connect==14.3
, para garantir que o pacote mais recente esteja instalado. Embora não seja um requisito, isso ajudará a garantir que você possa usar os recursos mais recentes com suporte para esse cluster.
Configurar as propriedades da conexão
Nesta seção, você configurará propriedades para estabelecer uma conexão entre o Databricks Connect e o cluster ou computação sem servidor do Azure Databricks, que inclui o seguinte:
- O nome da instância do workspace do Azure Databricks. Este é o valor do Nome de host do servidor para a computação. Consulte Obter os detalhes da conexão para um recurso de computação do Azure Databricks.
- Quaisquer outras propriedades necessárias para o tipo de autenticação do Databricks que você deseja usar.
Observação
A autenticação U2M (usuário para computador) do OAuth tem suporte no SDK do Databricks para Python 0.19.0 e superior. Talvez seja necessário atualizar a versão instalada do seu projeto de código do SDK do Databricks para Python para 0.19.0 ou superior para usar a autenticação U2M do OAuth. Confira Introdução ao SDK do Databricks para Python.
Para autenticação U2M do OAuth, você precisa usar a CLI do Databricks para autenticação antes de executar o código Python. Confira o Tutorial.
Autenticação M2M (máquina a máquina) do OAuth A autenticação M2M (máquina a máquina) do OAuth tem suporte no SDK do Databricks para Python 0.18.0 e superior. Talvez seja necessário atualizar a versão instalada do seu projeto de código do SDK do Databricks para Python para 0.18.0 ou superior para usar a autenticação M2M do OAuth. Confira Introdução ao SDK do Databricks para Python.
O SDK do Databricks para o Python ainda não implementou a autenticação de identidades gerenciadas pelo Azure.
Configurar uma conexão com um cluster
Para configurar uma conexão com um cluster, você precisará da ID do cluster. Obtenha a ID do cluster na URL. Confira a URL e ID do cluster.
Você pode configurar a conexão com o cluster de uma das seguintes maneiras. O Databricks Connect pesquisa propriedades de configuração na ordem a seguir e usa a primeira configuração encontrada. Para obter informações de configuração avançada, consulte Uso avançado do Databricks Connect para Python.
- O método remote() da classe DatabricksSession.
- Um perfil de configuração do Databricks
- A variável de ambiente DATABRICKS_CONFIG_PROFILE
- Uma variável de ambiente para cada propriedade de configuração
- Um perfil de configuração do Databricks chamado DEFAULT
O método remote()
da classe DatabricksSession
Para essa opção, que se aplica somente à autenticação de token de acesso pessoal do Azure Databricks, especifique o nome da instância do workspace, o token de acesso pessoal do Azure Databricks e a ID do cluster.
Você pode inicializar a classe DatabricksSession
de várias maneiras, conforme 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
. - Definir a cadeia de conexão do Spark Connect em
DatabricksSession.builder.remote()
.
Em vez de especificar essas propriedades de conexão em seu código, o 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 você forneça alguma implementação das funções retrieve_*
propostas para obter as propriedades necessárias do usuário ou de algum outro repositório de configurações, 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 que contém 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 necessários para cada tipo de autenticação são os seguintes:
- Para autenticação de token de acesso pessoal do Azure Databricks:
host
etoken
. - Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível):
host
,client_id
, eclient_secret
. - Para autenticação U2M (usuário para computador) do OAuth (onde compatível):
host
. - No caso da autenticação de entidades de serviço do Microsoft Entra ID (antigo Azure Active Directory):
host
,azure_tenant_id
,azure_client_id
,azure_client_secret
e, possivelmente,azure_workspace_resource_id
. - Para autenticação da CLI do Azure:
host
. - Para Autenticação de identidades gerenciadas do Azure (onde há suporte):
host
,azure_use_msi
,azure_client_id
e possivelmenteazure_workspace_resource_id
.
Em seguida, defina o nome desse perfil de configuração por meio da classe Config
.
Você pode especificar cluster_id
de algumas maneiras, conforme a seguir:
- Inclua o campo
cluster_id
em 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 junto com o campo
cluster_id
.
Se você já tiver definido a variável de ambiente DATABRICKS_CLUSTER_ID
com a ID do cluster, não precisará especificar também 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 Azure Databricks que contém 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á tiver definido a variável de ambiente DATABRICKS_CLUSTER_ID
com a ID do cluster, não precisará especificar também 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
etoken
. - Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível):
host
,client_id
, eclient_secret
. - Para autenticação U2M (usuário para computador) do OAuth (onde compatível):
host
. - No caso da autenticação de entidades de serviço do Microsoft Entra ID (antigo Azure Active Directory):
host
,azure_tenant_id
,azure_client_id
,azure_client_secret
e, possivelmente,azure_workspace_resource_id
. - Para autenticação da CLI do Azure:
host
. - Para Autenticação de identidades gerenciadas do Azure (onde há suporte):
host
,azure_use_msi
,azure_client_id
e possivelmenteazure_workspace_resource_id
.
Defina a variável de ambiente DATABRICKS_CONFIG_PROFILE
para o nome do perfil de configuração personalizado. 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 essa 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 de token de acesso pessoal do Azure Databricks:
DATABRICKS_HOST
eDATABRICKS_TOKEN
. - Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível):
DATABRICKS_HOST
,DATABRICKS_CLIENT_ID
, eDATABRICKS_CLIENT_SECRET
. - Para autenticação U2M (usuário para computador) do OAuth (onde compatível):
DATABRICKS_HOST
. - No caso da autenticação de entidades de serviço do Microsoft Entra ID (antigo Azure Active Directory):
DATABRICKS_HOST
,ARM_TENANT_ID
,ARM_CLIENT_ID
,ARM_CLIENT_SECRET
e, possivelmente,DATABRICKS_AZURE_RESOURCE_ID
. - Para autenticação da CLI do Azure:
DATABRICKS_HOST
. - Para Autenticação de identidades gerenciadas do Azure (onde há suporte):
DATABRICKS_HOST
,ARM_USE_MSI
,ARM_CLIENT_ID
e possivelmenteDATABRICKS_AZURE_RESOURCE_ID
.
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 Azure Databricks que contém 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á tiver definido a variável de ambiente DATABRICKS_CLUSTER_ID
com a ID do cluster, não precisará especificar também 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
etoken
. - Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível):
host
,client_id
, eclient_secret
. - Para autenticação U2M (usuário para computador) do OAuth (onde compatível):
host
. - No caso da autenticação de entidades de serviço do Microsoft Entra ID (antigo Azure Active Directory):
host
,azure_tenant_id
,azure_client_id
,azure_client_secret
e, possivelmente,azure_workspace_resource_id
. - Para autenticação da CLI do Azure:
host
. - Para Autenticação de identidades gerenciadas do Azure (onde há suporte):
host
,azure_use_msi
,azure_client_id
e possivelmenteazure_workspace_resource_id
.
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
Importante
Esse recurso está em uma versão prévia.
O Databricks Connect dá suporte à conexão com a computação sem servidor. Para usar esse recurso, os requisitos para se conectar à computação sem servidor devem ser atendidos. Confira os Requisitos
Importante
Este recurso tem as seguintes limitações:
- Todas as limitações do Databricks Connect para Python
- Todas as limitações da computação sem servidor
- Somente as dependências do Python incluídas como parte do ambiente de computação sem servidor podem ser usadas para UDFs. Consulte Ambiente do sistema. Dependências adicionais não podem ser instaladas.
- Não há suporte para UDFs com módulos personalizados.
Você pode configurar uma conexão com a computação sem servidor de uma das seguintes maneiras:
Defina a variável de ambiente local
DATABRICKS_SERVERLESS_COMPUTE_ID
comoauto
. Se a variável de ambiente estiver definida, o Databricks Connect ignorará ocluster_id
.Em um perfil de configuração local do Databricks, defina
serverless_compute_id = auto
e faça referência a esse perfil do 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 Python do Databricks Connect 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()
Observação
A sessão de computação sem servidor atinge o tempo limite após 10 minutos de inatividade. Depois disso, o processo do Python precisa ser reiniciado no lado do cliente para criar uma nova sessão do Spark para se conectar à computação sem servidor.
Validar a conexão com o Databricks
Para validar se o seu ambiente, as credenciais padrão e a conexão com a computação estão configurados 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 incompatibilidade na instalação.
databricks-connect test
Como alternativa, use o shell pyspark
incluído como parte do Databricks Connect para Python e execute um comando simples. Para obter mais detalhes sobre o shell do PySpark, consulte Shell do PySpark.