Instale o Databricks Connect para Python

Observação

Este artigo aborda o Databricks Connect para Databricks Runtime 13.0 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

O workspace e clusters do Databricks de destino devem atender aos requisitos de configuraçãoclusters para o Databricks Connect.
Você deve instalar o Python 3 em sua máquina de desenvolvimento, e a versão secundária da instalação do cliente Python deve ser igual à versão secundária do Python dos seus clusters do Databricks. Para encontrar a versão secundária do Python dos seus clusters, consulte a seção “Ambiente do sistema” das notas sobre a versão do Databricks Runtime para seus clusters. Consulte notas do Databricks Runtime sobre versões de versão e compatibilidade.

Observação

Se você quiser usar UDFs do PySpark, é importante que a versão secundária do Python instalada em sua máquina de desenvolvimento corresponda à versão secundária do Python incluída no Databricks Runtime instalado nos clusters.
A versão principal e secundária do pacote do Databricks Connect deve corresponder à versão do Databricks Runtime. A Databricks recomenda que utilize sempre o pacote mais recente do Databricks Connect que corresponda à sua versão do Databricks Runtime. Por exemplo, ao usar clusters do Databricks Runtime 14.0, você também deve usar a versão 14.0 do pacote databricks-connect.

Observação

Consulte as notas sobre a versão do Databricks Connect para obter uma lista de versões disponíveis do Databricks Connect e atualizações de manutenção.

Não é necessário usar o pacote mais recente do Databricks Connect que corresponda à sua versão do Databricks Runtime. Para Databricks Runtime 13.3 LTS e acima, o senhor pode usar o pacote Databricks Connect contra todas as versões de Databricks Runtime em ou acima da versão do pacote Databricks Connect. No entanto, se quiser usar recursos disponíveis em versões posteriores do Databricks Runtime, o senhor deverá atualizar o pacote Databricks Connect de acordo.
A Databricks recomenda vivamente que tenha um ambiente virtual Python ativado para cada versão Python que utiliza com Databricks Connect. Os ambientes virtuais Python ajudam a garantir que você está usando as versões corretas do Python e do Databricks Connect juntos. Isso pode ajudar a reduzir ou abreviar a resolução de problemas técnicos relacionados. Veja como ativar um ambiente virtual Python para venv ou Poetry nas seções a seguir. Para mais informações sobre essas ferramentas, veja venv ou Poetry.

Ative um ambiente virtual Python com venv

Se você estiver usando venv em sua máquina de desenvolvimento e seus clusters estiverem executando Python 3.10, você deverá criar um ambiente venv com essa versão. O comando de exemplo a seguir gera os scripts para ativar um ambiente venv com Python 3.10 e, em seguida, esse comando coloca esses scripts em uma pasta oculta chamada .venv no diretório de trabalho atual:

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

Para usar esses scripts para ativar esse ambiente venv , consulte Como funcionam os venvs.

Avance para Configurar o cliente.

Ative um ambiente virtual Python com Poetry

Instale Poetry, se ainda não o fez.
Se você estiver usando o Poetry em sua máquina de desenvolvimento e seus clusters estiverem executando o Python 3.10, você deverá criar um ambiente virtual do Poetry com essa versão. No diretório raiz do seu projeto de código Python existente, instrua poetry para inicializar seu projeto de código Python para Poetry, executando o seguinte comando:
```
poetry init
```
Poetry exibe vários prompts para você completar. Nenhum desses prompts é específico do Databricks Connect. Para obter informações sobre esses prompts, consulte init.
Depois de concluir as solicitações, o Poetry adiciona um arquivo pyproject.toml ao seu projeto Python. Para obter informações sobre o arquivo pyproject.toml , consulte O arquivo pyproject.toml.
No diretório raiz do seu projeto de código Python, instrua poetry para ler o arquivo pyproject.toml , resolver as dependências e instalá-las, criar um arquivo poetry.lock para bloquear as dependências e, finalmente, criar um ambiente virtual. Para fazer isso, execute o seguinte comando:
```
poetry install
```
No diretório raiz do seu projeto de código Python, instrua poetry para ativar o ambiente virtual e entrar no shell. Para fazer isso, execute o seguinte comando:
```
poetry shell
```

Você saberá que seu ambiente virtual está ativado e o shell foi inserido quando o nome do ambiente virtual for exibido entre parênteses logo antes do prompt do terminal, por exemplo (my-project-py3.10).

Para desativar o ambiente virtual e sair do shell a qualquer momento, execute o comando exit.

Você saberá que saiu do shell quando o nome do ambiente virtual não for mais exibido entre parênteses logo antes do prompt do terminal.

Para obter mais informações sobre como criar e gerenciar ambientes virtuais do Poetry, consulte Gerenciando ambientes.

Configurar o cliente

Dica

Se já tiver a extensão Databricks para Visual Studio Code instalada, não será necessário seguir estas instruções de configuração.

A extensão Databricks para Visual Studio Code já possui suporte integrado para Databricks Connect para Databricks Runtime 13.0 e acima. Avance para o código de depuração usando o Databricks Connect para a extensão Databricks para Visual Studio Code.

Depois de atender aos requisitos do Databricks Connect, conclua as etapas a seguir para configurar o cliente Databricks Connect.

passo 1: Instalar o cliente Databricks Connect

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

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 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
```
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.0.*"  # 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.

Vá para a etapa 2: 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 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
```
Com seu ambiente virtual ainda ativado, instale o cliente Databricks Connect executando o comando add .
```
poetry add databricks-connect@~14.0  # 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.0 em vez de databricks-connect==14.0, 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.

passo 2: configurar as propriedades da conexão

Nesta seção, você configura propriedades para estabelecer uma conexão entre o Databricks Connect e seus clusters remotos do Databricks. Essas propriedades incluem configurações para autenticar o Databricks Connect com seus clusters.

Para o Databricks Connect for Databricks Runtime 13.1 e acima, o Databricks Connect inclui o Databricks SDK for Python. Este SDK implementa o padrão de autenticação unificada do cliente Databricks , uma abordagem arquitetônica e programática consolidada e consistente para autenticação. Esta abordagem torna a configuração e a automação da autenticação com Databricks mais centralizada e previsível. Ele permite que você configure a autenticação do Databricks uma vez e, em seguida, use essa configuração em várias ferramentas e SDKs do Databricks sem mais alterações na configuração de autenticação.

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.
O Databricks Connect for Databricks Runtime 13.0 dá suporte apenas à autenticação access token pessoal do Databricks para autenticação.

Colete as propriedades de configuração a seguir.
- O nome da instância do espaço de trabalho do Databricks. É igual ao valor hostnamedo servidor para seus clusters; consulte Obter detalhes de conexão para um recurso de computação do Databricks.
- O ID dos seus clusters. Você pode obter o ID clusters na URL. Consulte URL e IDclusters .
- Quaisquer outras propriedades necessárias para o tipo de autenticação do Databricks compatível que você deseja usar. Essas propriedades são descritas ao longo desta seção.

Configure a conexão dentro do seu código. O Databricks Connect procura propriedades de configuração na seguinte ordem até encontrá-las. Depois de encontrá-los, ele para de pesquisar as opções restantes. Os detalhes de cada opção aparecem após a tabela a seguir:

Opção de propriedades de configuração	Aplica-se a
O método `remote()` da classe `DatabricksSession`	Somente autenticação access token pessoal do Databricks
Um perfil de configuração do Databricks	Todos os tipos de autenticação do Databricks
A variável de ambiente `SPARK_REMOTE`	Somente autenticação access token pessoal do Databricks
A variável de ambiente `DATABRICKS_CONFIG_PROFILE`	Todos os tipos de autenticação do Databricks
Uma variável de ambiente para cada propriedade de configuração	Todos os tipos de autenticação do Databricks
Um perfil de configuração do Databricks chamado `DEFAULT`	Todos os tipos de autenticação do Databricks

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

Databricks não recomenda que você especifique diretamente essas propriedades de conexão em seu código. Em vez disso, a Databricks recomenda configurar propriedades através de variáveis de ambiente ou ficheiros de configuração, conforme descrito ao longo desta secção. Os exemplos de código a seguir pressupõem que você mesmo 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 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()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).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 básica (legado): host, username e password.
- 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.
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 SPARK_REMOTE

Para esta opção, que se aplica apenas à autenticação access token pessoal do Databricks , defina a variável de ambiente SPARK_REMOTE como as strings a seguir, substituindo os espaços reservados pelos valores apropriados.
```
sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>
```
Em seguida, inicialize a classe DatabricksSession da seguinte maneira:
```
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
```
Para definir variável de ambiente, consulte a documentação do seu sistema operacional.
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 básica (legado): host, username e password.
- 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

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()
```
Para definir variável de ambiente, consulte a documentação do seu sistema operacional.
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 básica (legado): DATABRICKS_HOST, DATABRICKS_USERNAME e DATABRICKS_PASSWORD.
- 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.
Em seguida, inicialize a classe DatabricksSession da seguinte maneira:
```
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
```
Para definir variável de ambiente, consulte a documentação do seu sistema operacional.
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 básica (legado): host, username e password.
- 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.
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()
```

Valide seu ambiente e a conexão com os clusters do Databricks
- O comando a seguir verificará se seu ambiente, as credenciais do default e a conexão com os clusters estão todos configurados corretamente para o Databricks Connect.
```
databricks-connect test
```
  Esse comando obtém as credenciais do default configuradas no ambiente (como o perfil de configuração DEFAULT ou por meio da variável de ambiente).
  
  O comando falha com um código de saída diferente de zero e uma mensagem de erro correspondente quando detecta qualquer incompatibilidade na configuração.
- Além disso, o senhor também pode usar o shell pyspark que está incluído como parte do Databricks Connect for Python. iniciar o shell executando:
```
pyspark
```
  O shell Spark aparece, por exemplo:
```
Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>
```
  No prompt >>> , execute um comando simples do PySpark, como spark.range(1,10).show(). Se não houver erros, você se conectou com sucesso.
  
  Se você se conectou com sucesso, para interromper o shell Spark, pressione Ctrl + d ou Ctrl + z ou execute o comando quit() ou exit().
  
  Para obter mais detalhes sobre o binário databricks-connect, consulte Uso avançado do Databricks Connect para Python