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.

    Usar o pacote mais recente do Databricks Connect que corresponda à sua versão do Databricks Runtime não é um requisito. Para o Databricks Runtime 13.0 e acima, você pode usar o pacote Databricks Connect em todas as versões do Databricks Runtime iguais ouacimaes à versão do pacote Databricks Connect. No entanto, se quiser utilizar recursos que estão disponíveis em versões posteriores do Databricks Runtime, deve atualizar o pacote Databricks Connect em conformidade.

  • 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

  1. Instale Poetry, se ainda não o fez.

  2. 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
    
  3. 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.

  4. 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.

  5. 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
    
  6. 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

  1. 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
    
  2. 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

  1. 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
    
  2. 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

  1. Colete as propriedades de configuração a seguir.

  2. 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

    1. O método remote() da classe DatabricksSession

    Somente autenticação access token pessoal do Databricks

    1. Um perfil de configuração do Databricks

    Todos os tipos de autenticação do Databricks

    1. A variável de ambiente SPARK_REMOTE

    Somente autenticação access token pessoal do Databricks

    1. A variável de ambiente DATABRICKS_CONFIG_PROFILE

    Todos os tipos de autenticação do Databricks

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

    Todos os tipos de autenticação do Databricks

    1. Um perfil de configuração do Databricks chamado DEFAULT

    Todos os tipos de autenticação do Databricks

    1. 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 o Secret Manager clouds do Google.

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

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

      Você pode especificar cluster_id de algumas maneiras, como segue:

      • Inclua o campo cluster_id em seu perfil de configuração e especifique apenas o nome do perfil de configuração.

      • Especifique o nome do perfil de configuração junto com o campo cluster_id .

      Se você já configurou a variável de ambiente DATABRICKS_CLUSTER_ID com o ID dos clusters , também não será necessário especificar cluster_id.

      O código para cada uma dessas abordagens é o seguinte:

      # Include the cluster_id field in your configuration profile, and then
      # just specify the configuration profile's name:
      from databricks.connect import DatabricksSession
      
      spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()
      
      # Specify the configuration profile name along with the cluster_id field.
      # In this example, retrieve_cluster_id() assumes some custom implementation that
      # you provide to get the cluster ID from the user or from some other
      # configuration store:
      from databricks.connect import DatabricksSession
      from databricks.sdk.core import Config
      
      config = Config(
        profile    = "<profile-name>",
        cluster_id = retrieve_cluster_id()
      )
      
      spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()
      
    3. 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.

    4. 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:

      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.

    5. 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:

      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.

    6. 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:

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