Configuração de computação para o Databricks Connect

Artigo
11/24/2024

Observação

Esse artigo aborda o Databricks Connect para Databricks Runtime 13.3 LTS e superior.

Neste artigo, você configura propriedades para estabelecer uma conexão entre o Databricks Connect e o cluster do Azure Databricks ou a computação sem servidor. Essas informações se aplicam à versão Python e Scala do Databricks Connect, a menos que seja indicado o contrário.

O Databricks Connect permite conectar IDEs populares, como Visual Studio Code, PyCharm, RStudio Desktop, IntelliJ IDEA, servidores do notebook e outros aplicativos personalizados a clusters do Azure Databricks. Confira O que é o Databricks Connect?.

Requisitos

Para configurar uma conexão com a computação do Databricks, você deve ter:

Databricks Connect instalado. Para obter os requisitos de instalação e as etapas para versões de idioma específicas do Databricks Connect, consulte:
Uma conta e um workspace do Azure Databricks que têm o Catálogo do Unity habilitado. Confira Configurar e gerenciar o Catálogo do Unity e Habilitar um espaço de trabalho para o Catálogo do Unity.
Um cluster do Azure Databricks com o Databricks Runtime 13.3 LTS ou superior.
A versão do Databricks Runtime do cluster deve ser igual ou superior à versão do pacote do Databricks Connect. O Databricks recomenda que você sempre use o pacote mais recente do Databricks Connect que corresponda à sua versão do Databricks Runtime. Para usar recursos disponíveis em versões posteriores do Databricks Runtime, você deve atualizar o pacote do Databricks Connect. Confira as notas sobre a versão do Databricks Connect para ver uma lista das atualizações disponíveis do Databricks Connect. Para obter as notas de versão do Databricks Runtime, consulte versões de notas de versão do Databricks Runtime e compatibilidade.
O cluster deve usar um modo de acesso de cluster Atribuído ou Compartilhado. Consulte Modos de acesso.

Instalação

Antes de começar, você precisa do seguinte:

Se você estiver se conectando a um cluster, o ID do cluster. Você pode recuperar a ID do cluster da URL. Confira a URL e ID do cluster.
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. Atualize a versão instalada do SDK do Databricks para Python do projeto de código para 0.19.0 ou superior para usar a autenticação OAuth U2M. 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. Atualize a versão instalada do SDK do Databricks para Python do projeto de código 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

Há várias maneiras de configurar a conexão com o cluster. 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 DatabricksSession classe de várias maneiras:

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.

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:

Python

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

Scala

// Set the host, token, and clusterId fields in DatabricksSession.builder.
// If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
// cluster's ID, you do not also need to set the clusterId field here.
import com.databricks.connect.DatabricksSession

val spark = DatabricksSession.builder()
    .host(retrieveWorkspaceInstanceName())
    .token(retrieveToken())
    .clusterId(retrieveClusterId())
    .getOrCreate()

Python

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

Scala

// 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 clusterId field here.
import com.databricks.connect.DatabricksSession
import com.databricks.sdk.core.DatabricksConfig

val config = new DatabricksConfig()
    .setHost(retrieveWorkspaceInstanceName())
    .setToken(retrieveToken())
val spark = DatabricksSession.builder()
    .sdkConfig(config)
    .clusterId(retrieveClusterId())
    .getOrCreate()

Python

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

Scala

// Specify a Databricks configuration profile along with the clusterId 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 clusterId field here.
import com.databricks.connect.DatabricksSession
import com.databricks.sdk.core.DatabricksConfig

val config = new DatabricksConfig()
    .setProfile("<profile-name>")
val spark = DatabricksSession.builder()
    .sdkConfig(config)
    .clusterId(retrieveClusterId())
    .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 e token.
Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível): host, client_id, e client_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 possivelmente azure_workspace_resource_id.

Em seguida, defina o nome desse perfil de configuração por meio da classe de configuração.

Você pode especificar cluster_id de duas maneiras:

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:

Python

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

Scala

// Include the cluster_id field in your configuration profile, and then
// just specify the configuration profile's name:
import com.databricks.connect.DatabricksSession
import com.databricks.sdk.core.DatabricksConfig

val config = new DatabricksConfig()
    .setProfile("<profile-name>")
    val spark = DatabricksSession.builder()
    .sdkConfig(config)
    .getOrCreate()

Python

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

Scala

// Specify a Databricks configuration profile along with the clusterId 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 clusterId field here.
import com.databricks.connect.DatabricksSession
import com.databricks.sdk.core.DatabricksConfig

val config = new DatabricksConfig()
    .setProfile("<profile-name>")
val spark = DatabricksSession.builder()
    .sdkConfig(config)
    .clusterId(retrieveClusterId())
    .getOrCreate()

A variável de ambiente `DATABRICKS_CONFIG_PROFILE`

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 e token.
Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível): host, client_id, e client_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 possivelmente azure_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 DatabricksSession classe:

Python

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Scala

import com.databricks.connect.DatabricksSession

val 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 e DATABRICKS_TOKEN.
Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível): DATABRICKS_HOST, DATABRICKS_CLIENT_ID, e DATABRICKS_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 possivelmente DATABRICKS_AZURE_RESOURCE_ID.

Em seguida, inicialize a DatabricksSession classe:

Python

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Scala

import com.databricks.connect.DatabricksSession

val spark = DatabricksSession.builder().getOrCreate()

Um perfil de configuração do Databricks chamado `DEFAULT`

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 e token.
Para aautenticação OAuth de máquina a máquina (M2M) (quando compatível): host, client_id, e client_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 possivelmente azure_workspace_resource_id.

Nomeie esse perfil de configuração DEFAULT.

Em seguida, inicialize a DatabricksSession classe:

Python

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Scala

import com.databricks.connect.DatabricksSession

val 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 para Python 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:

Esse recurso só tem suporte no Databricks Connect para Python.
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 Imagens de cliente sem servidor. 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 como auto. Se a variável de ambiente estiver definida, o Databricks Connect ignorará o cluster_id.
Em um perfil de configuração local do Databricks, defina serverless_compute_id = autoe faça referência a esse perfil do seu código.
```
[DEFAULT]
host = https://my-workspace.cloud.databricks.com/
serverless_compute_id = auto
token = dapi123...
```
Ou use uma das seguintes opções:

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, uma nova sessão do Spark deve ser criada usando getOrCreate() 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

No Databricks Connect 14.3 e superior, você também pode validar seu ambiente usando validateSession():

DatabricksSession.builder.validateSession(True).getOrCreate()

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

Compartilhar via

Configuração de computação para o Databricks Connect

Requisitos

Instalação

Configurar uma conexão com um cluster

O método `remote()` da classe `DatabricksSession`

Python

Scala

Python

Scala

Python

Scala

Um perfil de configuração do Databricks

Python

Scala

Python

Scala

A variável de ambiente `DATABRICKS_CONFIG_PROFILE`

Python

Scala

Uma variável de ambiente para cada propriedade de configuração

Python

Scala

Um perfil de configuração do Databricks chamado `DEFAULT`

Python

Scala

Configurar uma conexão com a computação sem servidor

Validar a conexão com o Databricks

Desabilitar o Databricks Connect

Comentários

Recursos adicionais

Compartilhar via

Configuração de computação para o Databricks Connect

Requisitos

Instalação

Configurar uma conexão com um cluster

O método remote() da classe DatabricksSession

Python

Scala

Python

Scala

Python

Scala

Um perfil de configuração do Databricks

Python

Scala

Python

Scala

A variável de ambiente DATABRICKS_CONFIG_PROFILE

Python

Scala

Uma variável de ambiente para cada propriedade de configuração

Python

Scala

Um perfil de configuração do Databricks chamado DEFAULT

Python

Scala

Configurar uma conexão com a computação sem servidor

Validar a conexão com o Databricks

Desabilitar o Databricks Connect

Comentários

Recursos adicionais

O método `remote()` da classe `DatabricksSession`

A variável de ambiente `DATABRICKS_CONFIG_PROFILE`

Um perfil de configuração do Databricks chamado `DEFAULT`