Referência do Databricks Connect

Observação

Este artigo aborda o Databricks Connect para Databricks Runtime 13.0 e superior.

Para saber como começar rapidamente com o Databricks Connect para Databricks Runtime 13.0 e superior, consulte Databricks Connect.

Para obter informações sobre o Databricks Connect para versões anteriores do Databricks Runtime, consulte Databricks Connect para Databricks Runtime 12.2 LTS e versões inferiores.

O Databricks Connect permite conectar IDEs populares, como Visual Studio Code e PyCharm, servidores do notebook e outros aplicativos personalizados a clusters do Azure Databricks.

Este artigo explica como o Databricks Connect funciona, orienta você ao longo das etapas para começar a usar o Databricks Connect e explica como solucionar problemas que podem surgir ao usar o Databricks Connect.

Visão geral

O Databricks Connect é uma biblioteca de clientes do Databricks Runtime. Ele permite que você escreva trabalhos usando as APIs do Spark e execute-os remotamente em um cluster do Azure Databricks em vez de na sessão local do Spark.

Por exemplo, quando você executa o comando DataFrame spark.read.format(...).load(...).groupBy(...).agg(...).show() usando o Databricks Connect, a representação lógica do comando é enviada ao servidor do Spark em execução no Azure Databricks para execução no cluster remoto.

Com o Databricks Connect, você pode:

Executar trabalhos do Spark em grande escala em qualquer aplicativo Python. Em qualquer lugar que você puder import pyspark, agora você pode executar trabalhos do Spark diretamente de seu aplicativo, sem precisar instalar nenhum plug-in do IDE ou usar scripts de envio do Spark.

Observação

Atualmente, o Databricks Connect para Databricks Runtime 13.0 e superior dá suporte à execução apenas de aplicativos Python.
Executar o código em etapas e depurá-lo no IDE, mesmo quando trabalhar com um cluster remoto.
Iterar rapidamente ao desenvolver bibliotecas. Você não precisa reiniciar o cluster depois de alterar as dependências da biblioteca Python no Databricks Connect, pois cada sessão do cliente é isolada uma da outra no cluster.
Desligar clusters ociosos sem perder o trabalho. Como o aplicativo cliente é separado do cluster, ele não é afetado por reinicializações nem por atualizações do cluster, o que normalmente fará com que você perca todas as variáveis, os RDDs e os objetos de DataFrame definidos em um notebook.

Para o Databricks Runtime 13.0 e superior, o Databricks Connect agora é criado no Spark Connect de código aberto. O Spark Connect apresenta uma arquitetura cliente-servidor desacoplada para Apache Spark que permite conectividade remota com clusters Spark que usam a API do DataFrame e planos lógicos não resolvidos como o protocolo. Com essa arquitetura "V2" baseada no Spark Connect, o Databricks Connect se torna um cliente fino que é simples e fácil de usar. O Spark Connect pode ser inserido em todos os lugares para se conectar ao Azure Databricks: em IDEs, notebooks e aplicativos, permitindo que usuários individuais e parceiros criem novas experiências de usuário (interativas) com base no Databricks Lakehouse. Para obter mais informações sobre o Spark Connect, confira Introdução ao Spark Connect.

O Databricks Connect determina onde seu código é executado e depura, conforme mostrado na figura a seguir.

Figura mostrando onde o código do Databricks Connect é executado e depurado

Para executar o código: todo o código Python é executado localmente, enquanto todo o código PySpark que envolve operações do DataFrame é executado no cluster no workspace remoto do Azure Databricks e as respostas de execução são enviadas de volta ao chamador local.
Para depurar código: todo o Python é depurado localmente, enquanto todo o código PySpark continua sendo executado no cluster no workspace remoto do Azure Databricks. O código principal do mecanismo Spark não pode ser depurado diretamente do cliente.

Requisitos

Esta seção lista os requisitos para o Databricks Connect.

Um workspace do Azure Databricks e sua conta correspondente que estão habilitadas para o Catálogo do Unity. Confira Introdução ao uso do Catálogo do Unity e Habilitar um workspace do Catálogo do Unity.
Um cluster com o Databricks Runtime 13.0 ou superior instalado.
Há suporte apenas para clusters compatíveis com o Catálogo do Unity. Eles incluem clusters com modos de acesso atribuídos ou compartilhados. Consulte Modos de acesso.
Você deve instalar o Python 3 em seu computador de desenvolvimento e a versão secundária da instalação do Python do cliente deve ser a mesma que a versão secundária do Python do cluster do Azure Databricks. A tabela mostra a versão do Python instalada com cada Databricks Runtime.

Versão do Databricks Runtime Versão do Python

13.2 ML, 13.2 3.10

13.1 ML, 13.1 3.10

13.0 ML, 13.0 3.10

Observação

Se você quiser usar UDFs do PySpark, é importante que a versão secundária do Python instalada no computador de desenvolvimento corresponda à versão secundária do Python incluída no Databricks Runtime instalado no cluster.
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. Isso pode ajudar a reduzir ou abreviar a resolução de problemas técnicos relacionados.

Por exemplo, se você estiver usando o venv em seu computador de desenvolvimento e o cluster estiver executando o 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 dentro do 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, confira Como os venvs funcionam.
A versão principal e secundária do pacote do Databricks Connect deve corresponder à sua versão do Databricks Runtime. O Databricks recomenda que você sempre use o pacote mais recente do Databricks Connect que corresponda à sua versão do Databricks Runtime. Por exemplo, ao usar um cluster do Databricks Runtime 13.1, você também deverá usar o pacote databricks-connect==13.1.*.

Observação

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

O uso do pacote mais recente do Databricks Connect que corresponde à sua versão do Databricks Runtime não é um requisito. A partir do Databricks Runtime 13.0, você pode usar o pacote do Databricks Connect em todas as versões do Databricks Runtime em ou acima da versão do pacote do Databricks Connect. No entanto, se você quiser usar recursos que estão disponíveis em versões posteriores do Databricks Runtime, atualize o pacote do Databricks Connect adequadamente.

Versão do Databricks Runtime	Versão do Python
13.2 ML, 13.2	3.10
13.1 ML, 13.1	3.10
13.0 ML, 13.0	3.10

Configurar o cliente

Conclua as etapas a seguir para configurar o cliente local do Databricks Connect.

Observação

Antes de começar a configurar o cliente local do Databricks Connect, você precisa atender aos requisitos do Databricks Connect.

Dica

Se você já tiver a extensão do Databricks para Visual Studio Code instalada, não precisará seguir estas instruções de instalação.

A extensão do Databricks para Visual Studio Code já tem suporte interno para o Databricks Connect para Databricks Runtime 13.0 e superior. Pule para Executar ou depurar o código Python com o Databricks Connect na documentação da extensão do Databricks para Visual Studio Code.

Etapa 1: instalar o cliente do Databricks Connect

Com o ambiente virtual ativado, desinstale o PySpark, se ele já estiver instalado, executando o comando uninstall. Isso é necessário porque o pacote databricks-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 comando show.
```
# 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==13.1.*"  # 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 de databricks-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.

Etapa 2: configurar as propriedades da conexão

Nesta seção, você configurará propriedades para estabelecer uma conexão entre o Databricks Connect e o cluster remoto do Azure Databricks. Essas propriedades incluem configurações para autenticar o Databricks Connect com seu cluster.

A partir do Databricks Connect para Databricks Runtime 13.1 e superior, o Databricks Connect inclui o SDK do Databricks para Python. Este SDK implementa o padrão de autenticação unificada do cliente do Databricks, uma abordagem arquitetônica e programática consolidada e consistente de autenticação. Essa abordagem ajuda a tornar a configuração e a automação da autenticação com o Azure Databricks mais centralizada e previsível. Ela permite que você configure a autenticação do Azure Databricks uma vez e use essa configuração em várias ferramentas e SDKs do Azure Databricks sem mais alterações posteriores na configuração da autenticação.

Observação

O SDK do Databricks para Python ainda não implementou a autenticação de MSI do Azure.

O Databricks Connect para Databricks Runtime 13.0 dá suporte apenas a autenticação de tokens de acesso pessoal do Azure Databricks para autenticação.

Colete as propriedades de configuração a seguir.
- O nome da instância do workspace do Azure Databricks. Este é o mesmo que o valor Nome do host do servidor do seu cluster; confira Obter detalhes da conexão de um cluster.
- A ID do seu cluster. Obtenha a ID do cluster na URL. Confira a URL e ID do cluster.
- Quaisquer outras propriedades que sejam necessárias para o tipo de autenticação do Databricks que você deseja usar, como segue.
Configure a conexão em seu código. O Databricks Connect pesquisa propriedades de configuração na ordem a seguir até encontrá-las. Depois de encontrá-las, ele para de pesquisar pelas opções restantes:
1. Somente para autenticação de token de acesso pessoal do Azure Databricks, configuração direta de propriedades de conexão, especificada por meio 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.
  
  Os exemplos de código a seguir demonstram como inicializar a classe DatabricksSession para autenticação de token de acesso pessoal do Azure Databricks.
  
  O Databricks não recomenda que você especifique diretamente essas propriedades de conexão em seu código. Em vez disso, o Databricks recomenda configurar propriedades por meio de variáveis de ambiente ou arquivos de configuração, conforme descrito em opções posteriores. 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 repositório de configuração, como o Azure KeyVault.
```
# By setting fields in builder.remote:
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()

# Or, by using the Databricks SDK's Config class:
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()

# Or, specify a Databricks configuration profile and
# the cluster_id field separately:
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()

# Or, by setting the Spark Connect connection string in 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()
```
2. Para todos os tipos de autenticação do Azure Databricks, um nome de perfil de configuração do Azure Databricks, especificado usando 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.
  
  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 e token.
  - Para autenticação OAuth de usuário para máquina (U2M): host, azure_tenant_id, azure_client_id, e azure_client_secret.
  - Para autenticação da entidade de serviço do Azure: host, azure_tenant_id, azure_client_id, azure_client_secret e possivelmente azure_workspace_resource_id.
  - Para autenticação da CLI do Azure: host.
  Em seguida, defina o nome desse perfil de configuração por meio da classe Config.
  
  Como alternativa, você pode especificar cluster_id separadamente do perfil de configuração. Em vez de especificar diretamente a ID do cluster em seu código, os exemplos de código a seguir pressupõem que você forneça por conta própria alguma implementação da função retrieve_cluster_id proposta para obter a ID do cluster do usuário ou de algum outro repositório de configuração, como o Azure KeyVault.
  
  Por exemplo:
```
# Specify a Databricks configuration profile that contains the
# cluster_id field:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()
```
3. Somente para autenticação de token de acesso pessoal do Azure Databricks, a variável de ambiente SPARK_REMOTE
  
  Para essa opção, que se aplica somente à autenticação de token de acesso pessoal do Azure Databricks, defina a variável de ambiente SPARK_REMOTE como a cadeia de caracteres 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áveis de ambiente, confira a documentação do sistema operacional.
4. Para todos os tipos de autenticação do Azure Databricks, 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.
  
  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 e token.
  - Para autenticação OAuth de usuário para máquina (U2M): host, azure_tenant_id, azure_client_id, e azure_client_secret.
  - Para autenticação da entidade de serviço do Azure: host, azure_tenant_id, azure_client_id, azure_client_secret e possivelmente azure_workspace_resource_id.
  - Para autenticação da CLI do Azure: host.
  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()
```
  Para definir variáveis de ambiente, confira a documentação do sistema operacional.
5. Para todos os tipos de autenticação do Azure Databricks, uma variável de ambiente para cada propriedade de conexã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 e DATABRICKS_TOKEN.
  - Para autenticação OAuth de usuário para máquina (U2M): DATABRICKS_HOST, ARM_TENANT_ID, ARM_CLIENT_ID, e ARM_CLIENT_SECRET.
  - Para autenticação da entidade de serviço do Azure: 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.
  Em seguida, inicialize a classe DatabricksSession da seguinte maneira:
```
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
```
  Para definir variáveis de ambiente, confira a documentação do sistema operacional.
6. Para todos os tipos de autenticação do Azure Databricks, um perfil de configuração do Azure 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.
  
  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 e token.
  - Para autenticação OAuth de usuário para máquina (U2M): host, azure_tenant_id, azure_client_id, e azure_client_secret.
  - Para autenticação da entidade de serviço do Azure: host, azure_tenant_id, azure_client_id, azure_client_secret e possivelmente azure_workspace_resource_id.
  - Para autenticação da CLI do Azure: host.
  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()
```
Se você optar por usar a autenticação de tokens de acesso pessoal do Azure Databricks, poderá usar o utilitário pyspark incluído para testar a conectividade com o cluster do Azure Databricks da maneira apresentada a seguir.
- Com seu ambiente virtual ainda ativado, execute o comando a seguir:
  
  Se você definiu a variável de ambiente SPARK_REMOTE anteriormente, execute o comando a seguir:
```
pyspark
```
  Se você não definiu a variável de ambiente SPARK_REMOTE anteriormente, execute o comando a seguir:
```
pyspark --remote "sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>"
```
- O shell do Spark é exibido, 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 PySpark simples, como spark.range(1,10).show(). Se não houver erros, você se conectou com sucesso.
- Se você tiver se conectado com sucesso, para interromper o shell do Spark, pressione Ctrl + d ou Ctrl + z, ou execute o comando quit() ou exit().

Usar o Databricks Connect

Estas seções descrevem como configurar muitos IDEs populares e servidores de notebook para usar o cliente do Databricks Connect. Ou você pode usar o shell interno do Spark.

JupyterLab com Python

Observação

Antes de começar a usar o Databricks Connect, você precisa atender aos requisitos e configurar o cliente para o Databricks Connect.

Para usar o Databricks Connect com o JupyterLab e Python, siga estas instruções.

Para instalar o JupyterLab, com o ambiente virtual Python ativado, execute o seguinte comando no terminal ou no Prompt de Comando:
```
pip3 install jupyterlab
```
Para iniciar o JupyterLab no navegador da Web, execute o seguinte comando no ambiente virtual Python ativado:
```
jupyter lab
```
Se o JupyterLab não aparecer no navegador da Web, copie o URL que começa com localhost ou 127.0.0.1 do seu ambiente virtual e insira-o na barra de endereços do navegador da Web.
Crie um novo notebook: no JupyterLab, clique em Arquivo > Novo > Notebook no menu principal, selecione Python 3 (ipykernel) e clique em Selecionar.
Na primeira célula do notebook, insira o código de exemplo ou seu próprio código. Se você usar seu próprio código, deverá inicializar DatabricksSession no mínimo conforme mostrado no código de exemplo.
Para executar o notebook, clique em Executar > Executar Todas as Células. Todo o código Python é executado localmente, enquanto todo o código PySpark que envolve operações do DataFrame é executado no cluster no workspace remoto do Azure Databricks e as respostas de execução são enviadas de volta para o chamador local.
Para depurar o notebook, clique no ícone de bug (Habilitar Depurador) ao lado de Python 3 (ipykernel) na barra de ferramentas do notebook. Defina um ou mais pontos de interrupção e clique em Executar > Executar Todas as Células. Todo o Python é depurado localmente, enquanto todo o código PySpark continua a ser executado no cluster no workspace remoto do Azure Databricks. O código principal do mecanismo Spark não pode ser depurado diretamente do cliente.
Para desligar o JupyterLab, clique em Arquivo > Desligado. Se o processo do JupyterLab ainda estiver em execução no seu terminal ou prompt de comando, interrompa esse processo pressionando Ctrl + c e, em seguida, inserindo y para confirmar.

Para obter instruções de depuração mais específicas, confira Depurador.

Jupyter Notebook clássico com Python

Observação

Antes de começar a usar o Databricks Connect, você precisa atender aos requisitos e configurar o cliente para o Databricks Connect.

Para usar o Databricks Connect com o Jupyter Notebook clássico e Python, siga estas instruções.

Para instalar o Jupyter Notebook clássico, com o ambiente virtual Python ativado, execute o seguinte comando no seu terminal ou no Prompt de Comando:
```
pip3 install notebook
```
Para iniciar o Jupyter Notebook clássico no navegador da Web, execute o seguinte comando no ambiente virtual Python ativado:
```
jupyter notebook
```
Se o Jupyter Notebook clássico não aparecer no navegador da Web, copie o URL que começa com localhost ou 127.0.0.1 do seu ambiente virtual e insira-o na barra de endereços do navegador da Web.
Crie um novo notebook: no Jupyter Notebook clássico, na guia Arquivos, clique em Novo > Python 3 (ipykernel).
Na primeira célula do notebook, insira o código de exemplo ou seu próprio código. Se você usar seu próprio código, deverá inicializar DatabricksSession no mínimo conforme mostrado no código de exemplo.
Para executar o notebook, clique em Célula > Executar Tudo. Todo o código Python é executado localmente, enquanto todo o código PySpark que envolve operações do DataFrame é executado no cluster no workspace remoto do Azure Databricks e as respostas de execução são enviadas de volta para o chamador local.
Para depurar o notebook, adicione a seguinte linha de código no início do notebook:

from IPython.core.debugger import set_trace

Em seguida, chame set_trace() para inserir instruções de depuração nesse ponto de execução do notebook. Todo o Python é depurado localmente, enquanto todo o código PySpark continua a ser executado no cluster no workspace remoto do Azure Databricks. O código principal do mecanismo Spark não pode ser depurado diretamente do cliente.
Para desligar o Jupyter Notebook clássico, clique em Arquivo > Fechar e Parar. Se o processo do Jupyter Notebook clássico ainda estiver em execução no seu terminal ou prompt de comando, interrompa esse processo pressionando Ctrl + c e, em seguida, inserindo y para confirmar.

Visual Studio Code com Python

Observação

Antes de começar a usar o Databricks Connect, você precisa atender aos requisitos e configurar o cliente para o Databricks Connect.

Dica

A extensão do Databricks para Visual Studio Code já tem suporte interno para o Databricks Connect para Databricks Runtime 13.0 e superior. Confira Executar ou depurar o código Python com o Databricks Connect na documentação da extensão do Databricks para Visual Studio Code.

Para usar o Databricks Connect com o Visual Studio Code e Python, siga estas instruções.

Inicie o Visual Studio Code.
Abra a pasta que contém o ambiente virtual do Python (Arquivo > Abrir Pasta).
No Terminal do Visual Studio Code (Exibir > Terminal), ative o ambiente virtual.
Defina o interpretador atual do Python para ser referenciado no ambiente virtual:
1. Na Paleta de Comandos (Exibir > Paleta de Comandos), digite Python: Select Interpreter e pressione Enter.
2. Selecione o caminho para o interpretador do Python referenciado no ambiente virtual.
Adicione à pasta um arquivo de código Python (.py) que contém o código de exemplo ou seu próprio código. Se você usar seu próprio código, deverá inicializar DatabricksSession no mínimo conforme mostrado no código de exemplo.
Para executar o código, clique em Executar > Sem Depuração no menu main. Todo o código Python é executado localmente, enquanto todo o código PySpark que envolve operações do DataFrame é executado no cluster no workspace remoto do Azure Databricks e as respostas de execução são enviadas de volta para o chamador local.
Para depurar o código:
1. Com o arquivo de código Python aberto, defina os pontos de interrupção em que você deseja que seu código pause durante a execução.
2. Clique no ícone Executar e Depurar na barra lateral ou em Exibir > Execução no menu principal.
3. Na exibição Executar e Depurar, clique no botão Executar e Depurar.
4. Siga as instruções na tela para começar a executar e depurar o código.
Todo o Python é depurado localmente, enquanto todo o código PySpark continua a ser executado no cluster no workspace remoto do Azure Databricks. O código principal do mecanismo Spark não pode ser depurado diretamente do cliente.

Para obter instruções de execução e depuração mais específicas, confira Configurar e executar o depurador e Depuração do Python no VS Code.

PyCharm com Python

Observação

Antes de começar a usar o Databricks Connect, você precisa atender aos requisitos e configurar o cliente para o Databricks Connect.

O IntelliJ IDEA Ultimate fornece suporte de plug-in para PyCharm com Python também. Para obter detalhes, confira Plug-in do Python para IntelliJ IDEA Ultimate.

Para usar o Databricks Connect com o PyCharm e Python, siga estas instruções.

Inicie o PyCharm.
Crie um projeto: clique em Arquivo > Novo Projeto.
Em Local, clique no ícone de pasta e selecione o caminho para seu ambiente virtual Python.
Selecione Interpretador configurado anteriormente.
Em Interpretador, clique nas reticências.
Clique em Interpretador do Sistema.
Em Interpretador, clique nas reticências e selecione o caminho completo para o interpretador do Python referenciado no ambiente virtual. Em seguida, clique em OK.
Clique em OK novamente.
Clique em Criar.
Clique em Criar de Fontes Existentes.
Adicione ao projeto um arquivo de código Python (.py) que contém o código de exemplo ou seu próprio código. Se você usar seu próprio código, deverá inicializar DatabricksSession no mínimo conforme mostrado no código de exemplo.
Com o arquivo de código Python aberto, defina os pontos de interrupção em que você deseja que seu código pause durante a execução.
Para executar o código, clique em Executar > Executar. Todo o código Python é executado localmente, enquanto todo o código PySpark que envolve operações do DataFrame é executado no cluster no workspace remoto do Azure Databricks e as respostas de execução são enviadas de volta para o chamador local.
Para depurar o código, clique em Executar > Depuração. Todo o Python é depurado localmente, enquanto todo o código PySpark continua a ser executado no cluster no workspace remoto do Azure Databricks. O código principal do mecanismo Spark não pode ser depurado diretamente do cliente.
Siga as instruções na tela para começar a executar ou depurar o código.

Para obter instruções mais específicas sobre execução e depuração, confira Executar sem nenhuma configuração prévia e Depurar.

Eclipse com PyDev

Observação

Antes de começar a usar o Databricks Connect, você precisa atender aos requisitos e configurar o cliente para o Databricks Connect.

Para usar o Databricks Connect e Eclipse com PyDev, siga estas instruções.

Inicie o Eclipse.
Criar um projeto: clique em Arquivo > Novo > Projeto > PyDev > Projeto PyDev e clique em Avançar.
Especifique um Nome do projeto.
Para Conteúdo do projeto, especifique o caminho para o ambiente virtual Python.
Clique em Configurar um interpretador antes de continuar.
Clique em Configuração manual.
Clique em Novo > Procurar python/pypy exe.
Procure e selecione o caminho completo para o interpretador do Python referenciado no ambiente virtual e, em seguida, clique em Abrir.
Na caixa de diálogo Selecionar interpretador, clique em OK.
Na caixa de diálogo Seleção necessária, clique em OK.
Na caixa de diálogo Preferências, clique em Aplicar e Fechar.
Na caixa de diálogo Projeto PyDev, clique em Concluir.
Clique em Abrir Perspectiva.
Adicione ao projeto um arquivo de código Python (.py) que contém o código de exemplo ou seu próprio código. Se você usar seu próprio código, deverá inicializar DatabricksSession no mínimo conforme mostrado no código de exemplo.
Com o arquivo de código Python aberto, defina os pontos de interrupção em que você deseja que seu código pause durante a execução.
Para executar o código, clique em Executar > Executar. Todo o código Python é executado localmente, enquanto todo o código PySpark que envolve operações do DataFrame é executado no cluster no workspace remoto do Azure Databricks e as respostas de execução são enviadas de volta para o chamador local.
Para depurar o código, clique em Executar > Depuração. Todo o Python é depurado localmente, enquanto todo o código PySpark continua a ser executado no cluster no workspace remoto do Azure Databricks. O código principal do mecanismo Spark não pode ser depurado diretamente do cliente.

Para obter instruções de execução e depuração mais específicas, confira Executando um programa.

Shell do Spark com Python

Observação

Antes de começar a usar o Databricks Connect, você precisa atender aos requisitos e configurar o cliente para o Databricks Connect.

O shell do Spark funciona apenas com a autenticação de tokens de acesso pessoal do Azure Databricks.

Para usar o Databricks Connect com o shell do Spark e Python, siga estas instruções.

Para iniciar o shell do Spark e conectá-lo ao cluster em execução, execute um dos seguintes comandos em seu ambiente virtual Python ativado:

Se você definiu a variável de ambiente SPARK_REMOTE anteriormente, execute o comando a seguir:

pyspark

Se você não definiu a variável de ambiente SPARK_REMOTE anteriormente, execute o comando a seguir:

pyspark --remote "sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>"

O shell do Spark é exibido, por exemplo:

Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
     ____              __
    / __/__  ___ _____/ /__
   _\ \/ _ \/ _ `/ __/  '_/
  /__ / .__/\_,_/_/ /_/\_\   version 13.x.dev0
     /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>

Veja Análise Interativa com o Shell do Spark para obter informações sobre como usar o shell do Spark com Python a fim de executar comandos no cluster.

Use a variável interna spark para representar o SparkSession no cluster em execução, por exemplo:

>>> df = spark.read.table("samples.nyctaxi.trips")
>>> df.show(5)
+--------------------+---------------------+-------------+-----------+----------+-----------+
|tpep_pickup_datetime|tpep_dropoff_datetime|trip_distance|fare_amount|pickup_zip|dropoff_zip|
+--------------------+---------------------+-------------+-----------+----------+-----------+
| 2016-02-14 16:52:13|  2016-02-14 17:16:04|         4.94|       19.0|     10282|      10171|
| 2016-02-04 18:44:19|  2016-02-04 18:46:00|         0.28|        3.5|     10110|      10110|
| 2016-02-17 17:13:57|  2016-02-17 17:17:55|          0.7|        5.0|     10103|      10023|
| 2016-02-18 10:36:07|  2016-02-18 10:41:45|          0.8|        6.0|     10022|      10017|
| 2016-02-22 14:14:41|  2016-02-22 14:31:52|         4.51|       17.0|     10110|      10282|
+--------------------+---------------------+-------------+-----------+----------+-----------+
only showing top 5 rows

Todo o código Python é executado localmente, enquanto todo o código PySpark que envolve operações do DataFrame é executado no cluster no workspace remoto do Azure Databricks e as respostas de execução são enviadas de volta para o chamador local.

Para interromper o shell do Spark, pressione Ctrl + d ou Ctrl + z, ou execute o comando quit() ou exit().

Exemplos de código

O Databricks fornece vários aplicativos de exemplo que mostram como usar o Databricks Connect. Consulte o repositório databricks-demos/dbconnect-examples no GitHub.

Você também pode usar os seguintes exemplos de código mais simples para experimentar o Databricks Connect. Esses exemplos pressupõem que você esteja usando a autenticação padrão para o Databricks Connect.

Este exemplo de código simples consulta a tabela especificada e mostra as cinco primeiras linhas da tabela especificada. Para usar uma tabela diferente, ajuste a chamada para spark.read.table.

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

df = spark.read.table("samples.nyctaxi.trips")
df.show(5)

Este exemplo de código mais longo faz o seguinte:

Cria um DataFrame na memória.
Cria uma tabela com o nome zzz_demo_temps_table dentro do esquema default. Se a tabela com esse nome já existir, a tabela será excluída primeiro. Para usar um esquema ou uma tabela diferente, ajuste as chamadas para spark.sql, temps.write.saveAsTable ou ambos.
Salva o conteúdo do DataFrame na tabela.
Executa uma consulta SELECT no conteúdo da tabela.
Mostra o resultado da consulta.
Exclui a tabela.

from databricks.connect import DatabricksSession
from pyspark.sql.types import *
from datetime import date

spark = DatabricksSession.builder.getOrCreate()

# Create a Spark DataFrame consisting of high and low temperatures
# by airport code and date.
schema = StructType([
  StructField('AirportCode', StringType(), False),
  StructField('Date', DateType(), False),
  StructField('TempHighF', IntegerType(), False),
  StructField('TempLowF', IntegerType(), False)
])

data = [
  [ 'BLI', date(2021, 4, 3), 52, 43],
  [ 'BLI', date(2021, 4, 2), 50, 38],
  [ 'BLI', date(2021, 4, 1), 52, 41],
  [ 'PDX', date(2021, 4, 3), 64, 45],
  [ 'PDX', date(2021, 4, 2), 61, 41],
  [ 'PDX', date(2021, 4, 1), 66, 39],
  [ 'SEA', date(2021, 4, 3), 57, 43],
  [ 'SEA', date(2021, 4, 2), 54, 39],
  [ 'SEA', date(2021, 4, 1), 56, 41]
]

temps = spark.createDataFrame(data, schema)

# Create a table on the Databricks cluster and then fill
# the table with the DataFrame's contents.
# If the table already exists from a previous run,
# delete it first.
spark.sql('USE default')
spark.sql('DROP TABLE IF EXISTS zzz_demo_temps_table')
temps.write.saveAsTable('zzz_demo_temps_table')

# Query the table on the Databricks cluster, returning rows
# where the airport code is not BLI and the date is later
# than 2021-04-01. Group the results and order by high
# temperature in descending order.
df_temps = spark.sql("SELECT * FROM zzz_demo_temps_table " \
  "WHERE AirportCode != 'BLI' AND Date > '2021-04-01' " \
  "GROUP BY AirportCode, Date, TempHighF, TempLowF " \
  "ORDER BY TempHighF DESC")
df_temps.show()

# Results:
#
# +-----------+----------+---------+--------+
# |AirportCode|      Date|TempHighF|TempLowF|
# +-----------+----------+---------+--------+
# |        PDX|2021-04-03|       64|      45|
# |        PDX|2021-04-02|       61|      41|
# |        SEA|2021-04-03|       57|      43|
# |        SEA|2021-04-02|       54|      39|
# +-----------+----------+---------+--------+

# Clean up by deleting the table from the Databricks cluster.
spark.sql('DROP TABLE zzz_demo_temps_table')

Migrar para o Databricks Connect mais recente

Siga essas diretrizes para migrar seu projeto de código Python existente ou ambiente de codificação do Databricks Connect para o Databricks Runtime 12.2 LTS e inferior para o Databricks Connect para o Databricks Runtime 13.0 e superior.

Observação

Atualmente, o Databricks Connect para Databricks Runtime 13.0 e superior dá suporte apenas a projetos baseados em Python e ambientes de codificação.

Instale a versão correta do Python conforme listado nos requisitos para corresponder ao cluster do Azure Databricks, se ele ainda não estiver instalado localmente.
Atualize o ambiente virtual Python para usar a versão correta do Python para corresponder ao cluster, se necessário. Para obter instruções, confira a documentação do provedor de ambiente virtual.
Com o ambiente virtual ativado, desinstale o PySpark do seu ambiente virtual:
```
pip3 uninstall pyspark
```
Com seu ambiente virtual ainda ativado, desinstale o Databricks Connect para o Databricks Runtime 12.2 LTS e versões inferiores:
```
pip3 uninstall databricks-connect
```
Com seu ambiente virtual ainda ativado, instale o Databricks Connect para Databricks Runtime 13.0 e superior:
```
pip3 install --upgrade "databricks-connect==13.1.*"  # 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 de databricks-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.
Atualize o código Python para inicializar a variável spark (que representa uma instanciação da classe DatabricksSession, semelhante a SparkSession no PySpark). Para obter exemplos de código, consulte Etapa 2: configurar propriedades de conexão.

Acessar Utilitários do Databricks

Esta seção descreve como usar o Databricks Connect para acessar os Utilitários do Databricks.

Você pode chamar funções do DBFS (Sistema de Arquivos do Databricks) de dentro de um workspace do Azure Databricks. Para fazer isso, use a variável WorkspaceClient da classe dbfs. Essa abordagem é semelhante à chamada de Utilitários do Databricks por meio da variável dbfs de um notebook dentro de um workspace. A classe WorkspaceClient pertence ao SDK do Databricks para Python, que está incluído no Databricks Connect para Databricks Runtime 13.0 e superior.

Dica

Você também pode usar o SDK do Databricks para Python para acessar qualquer API REST do Databricks disponível, não apenas a API do DBFS. Confira databricks-sdk no PyPI.

Para inicializar WorkspaceClient, você deve fornecer informações suficientes para autenticar o SDK do Databricks para Python com o workspace. Por exemplo, você pode:

Codifique o URL do espaço de trabalho e seu token de acesso diretamente em seu código e, em seguida, inicialize WorkspaceClient da seguinte maneira. Embora essa opção tenha suporte, o Databricks não recomenda essa opção, pois pode expor informações confidenciais, como tokens de acesso, se o código for verificado no controle de versão ou compartilhado de outra forma:
```
w = WorkspaceClient(host  = "https://<workspace-instance-name>",
                    token = "<access-token-value")
```
Crie ou especifique um perfil de configuração que contenha os campos host e token e, em seguida, inicialize o WorkspaceClient da seguinte maneira:
```
w = WorkspaceClient(profile = "<profile-name>")
```
Defina as variáveis de ambiente DATABRICKS_HOST e DATABRICKS_TOKEN da mesma maneira que definiu para o Databricks Connect e, em seguida, inicialize WorkspaceClient da seguinte maneira:
```
w = WorkspaceClient()
```

O SDK do Databricks para Python não reconhece a variável de ambiente SPARK_REMOTE do Databricks Connect.

Para obter opções adicionais de autenticação do Azure Databricks para o SDK do Databricks para Python, bem como inicializar AccountClient no SDK do Databricks para Python para acessar as APIs REST do Databricks disponíveis no nível da conta em vez de no nível do workspace, confira databricks-sdk no PyPI.

O exemplo a seguir cria um arquivo chamado zzz_hello.txt na raiz DBFS dentro do workspace, grava dados no arquivo, fecha o arquivo, lê os dados do arquivo e exclui o arquivo. Este exemplo pressupõe que as variáveis de ambiente DATABRICKS_HOST e DATABRICKS_TOKEN já foram definidas:

from databricks.sdk import WorkspaceClient
import base64

w = WorkspaceClient()

file_path  = "/zzz_hello.txt"
file_data  = "Hello, Databricks!"

# The data must be base64-encoded before being written.
file_data_base64 = base64.b64encode(file_data.encode())

# Create the file.
file_handle = w.dbfs.create(
  path      = file_path,
  overwrite = True
).handle

# Add the base64-encoded version of the data.
w.dbfs.add_block(
  handle = file_handle,
  data   = file_data_base64.decode()
)

# Close the file after writing.
w.dbfs.close(handle = file_handle)

# Read the file's contents and then decode and print it.
response = w.dbfs.read(path = file_path)
print(base64.b64decode(response.data).decode())

# Delete the file.
w.dbfs.delete(path = file_path)

Dica

Você também pode acessar o utilitário de segredos dos Utilitários do Databricks por meio de w.secrets, o utilitário de trabalhos por meio de w.jobs e o utilitário de biblioteca por meio de w.libraries.

Desabilitar o Databricks Connect

Os serviços do Databricks Connect (e do Spark Connect subjacente) podem ser desabilitados em qualquer cluster específico. Para desabilitar o serviço do Databricks Connect, defina a seguinte configuração do Spark no cluster.

spark.databricks.service.server.enabled false

Depois de desabilitado, todas as consultas do Databricks Connect que chegam ao cluster são rejeitadas com uma mensagem de erro apropriada.

Definir configurações do Hadoop

No cliente, você pode definir configurações do Hadoop usando a API spark.conf.set, que se aplica às operações de SQL e do DataFrame. As configurações do Hadoop definidas no sparkContext precisam ser feitas na configuração do cluster ou por meio de um notebook. Isso porque as configurações definidas em sparkContext não estão vinculadas às sessões de usuário, mas se aplicam a todo o cluster.

Solução de problemas

Esta seção descreve alguns problemas comuns que você pode encontrar no Databricks Connect e como resolve-los.

Nesta seção:

Erro: StatusCode.UNAVAILABLE, StatusCode.UNKNOWN, falha na resolução DNS ou cabeçalho http2 recebido com o status 500
Incompatibilidade de versão do Python
Instalações conflitantes do PySpark
Entrada conflitante ou ausente PATH para binários
A sintaxe do nome do arquivo, nome do diretório ou rótulo do volume está incorreta no Windows

Erro: StatusCode.UNAVAILABLE, StatusCode.UNKNOWN, falha na resolução DNS ou cabeçalho http2 recebido com o status 500

Problema: ao tentar executar o código com o Databricks Connect, você receberá uma mensagem de erro que contém cadeias de caracteres como StatusCode.UNAVAILABLE, StatusCode.UNKNOWN, DNS resolution failed ou Received http2 header with status: 500.

Possível causa: o Databricks Connect não pode alcançar o cluster.

Soluções recomendadas:

Verifique se o nome da instância do workspace está correto. Se você usar variáveis de ambiente, verifique se a variável de ambiente relacionada está disponível e é correta no computador de desenvolvimento local.
Verifique se a ID do cluster está correta. Se você usar variáveis de ambiente, verifique se a variável de ambiente relacionada está disponível e é correta no computador de desenvolvimento local.
Verifique se o cluster tem a versão correta personalizada do cluster compatível com o Databricks Connect.

Incompatibilidade de versão do Python

Verifique se a versão do Python que você está usando localmente tem, pelo menos, a mesma versão secundária que a versão no cluster (por exemplo, 3.10.11 em relação a 3.10.10 é adequado, mas 3.10 em relação a 3.9 não).

Se você tiver várias versões do Python instaladas localmente, verifique se o Databricks Connect está usando a correta definindo a variável de ambiente PYSPARK_PYTHON (por exemplo, PYSPARK_PYTHON=python3).

Instalações conflitantes do PySpark

O pacote databricks-connect entra em conflito com o PySpark. Ter os dois instalados causará erros ao inicializar o contexto do Spark no Python. Isso pode se manifestar de várias maneiras, incluindo erros de “fluxo corrompido” ou “classe não encontrada”. Se você tiver o PySpark instalado no ambiente do Python, verifique se ele foi desinstalado antes de instalar o databricks-connect. Depois de desinstalar o PySpark, lembre-se de reinstalar totalmente o pacote do Databricks Connect:

pip3 uninstall pyspark
pip3 uninstall databricks-connect
pip3 install --upgrade "databricks-connect==13.1.*"  # or X.Y.* to match your specific cluster version.

Entrada `PATH` conflitante ou ausente para binários

É possível que o PATH esteja configurado, ou seja, comandos como spark-shell executarão algum outro binário instalado anteriormente em vez do fornecido com o Databricks Connect. Você deve verificar se os binários do Databricks Connect têm precedência ou remover os instalados anteriormente.

Se você não consegue executar comandos como spark-shell, também é possível que o PATH não tenha sido configurado automaticamente pelo pip3 install e você precisará adicionar o diretório bin de instalação ao PATH manualmente. É possível usar o Databricks Connect com IDEs, mesmo que isso não esteja configurado.

A sintaxe do nome do arquivo, do nome do diretório ou do rótulo do volume está incorreta no Windows

Se estiver usando o Databricks Connect no Windows e receber:

The filename, directory name, or volume label syntax is incorrect.

O Databricks Connect foi instalado em um diretório com um espaço no caminho. Resolva isso instalando em um caminho de diretório sem espaços ou configurando o caminho usando o formato de nome curto.

Limitações

O Databricks Connect não dá suporte aos seguintes recursos e plataformas de terceiros do Azure Databricks.

Limitações da API do DataFrame do PySpark

A classe SparkContext e os métodos dela não estão disponíveis.
Não há suporte para RDDs (conjuntos de dados distribuídos resilientes) e conjuntos de dados. Há suporte apenas para DataFrames.

Limitações do Azure Databricks e do Databricks Connect

Não há suporte para consultas com duração superior a 3600 segundos. Haverá falha.
Não há suporte para a sincronização do ambiente de desenvolvimento local com o cluster remoto.
Verifique se a versão do Python e os pacotes do Python que você usa em seu ambiente de desenvolvimento local correspondem aos equivalentes instalados no cluster o máximo possível, para ajudar a garantir a compatibilidade de código e a reduzir erros inesperados de tempo de execução.
Há suporte apenas para o Python. Não há suporte para R, Scala e Java.
Não há suporte para treinamento distribuído.
O MLflow tem suporte, mas não a inferência de modelo com mlflow.pyfunc.spark_udf(spark, ...). Você pode carregar o modelo localmente com mlflow.pyfunc.load_model(<model>) ou encapsule-o como uma UDF personalizada do Pandas.
Não é possível alterar o nível de log log4j por meio do SparkContext.
Não há suporte para Mosaico.

Limitações do cluster do Azure Databricks

O usuário do workspace do Azure Databricks associado ao token de acesso usado pelo Databricks Connect deve ter permissões Pode Anexar a ou superior para o cluster de destino.
CREATE TABLE table AS SELECT ... Os comandos SQL nem sempre funcionam. Em vez disso, use spark.sql("SELECT ...").write.saveAsTable("table").
Só há suporte para a passagem de credenciais do Azure Active Directory em clusters standard que executam o Databricks Runtime 7.3 LTS e superior, e ela não é compatível com a autenticação da entidade de serviço.
Os tokens do Azure Active Directory (AD) não são atualizados automaticamente e expirarão uma hora após serem gerados inicialmente.
Os seguintes utilitários do Databricks:

Last updated on 2023-09-05

Compartilhar via

Referência do Databricks Connect

Visão geral

Requisitos

Configurar o cliente

Etapa 1: instalar o cliente do Databricks Connect

Etapa 2: configurar as propriedades da conexão

Usar o Databricks Connect

Nesta seção:

JupyterLab com Python

Jupyter Notebook clássico com Python

Visual Studio Code com Python

PyCharm com Python

Eclipse com PyDev

Shell do Spark com Python

Exemplos de código

Migrar para o Databricks Connect mais recente

Acessar Utilitários do Databricks

Desabilitar o Databricks Connect

Definir configurações do Hadoop

Solução de problemas

Nesta seção:

Erro: StatusCode.UNAVAILABLE, StatusCode.UNKNOWN, falha na resolução DNS ou cabeçalho http2 recebido com o status 500

Incompatibilidade de versão do Python

Instalações conflitantes do PySpark

Entrada PATH conflitante ou ausente para binários

A sintaxe do nome do arquivo, do nome do diretório ou do rótulo do volume está incorreta no Windows

Limitações

Limitações da API do DataFrame do PySpark

Limitações do Azure Databricks e do Databricks Connect

Limitações do cluster do Azure Databricks

Recursos adicionais

Entrada `PATH` conflitante ou ausente para binários