SDK do Databricks para Python

Neste artigo, o senhor aprenderá a automatizar operações na conta do Databricks, no espaço de trabalho e nos recursos relacionados com o Databricks SDK for Python. Este artigo complementa a documentação do Databricks SDK para Python no Read The Docs e os exemplos de código nos repositórios do Databricks SDK para Python no GitHub.

Observação

Esse recurso está em Beta e pode ser usado na produção.

Durante o período Beta, o Databricks recomenda que você pin uma dependência na versão secundária específica do SDK do Databricks para Python da qual seu código depende. Por exemplo, você pode pin dependências em arquivos como requirements.txt para venv ou pyproject.toml e poetry.lock para Poetry. Para obter mais informações sobre fixação de dependências, consulte Ambientes Virtuais e pacote para venv ou Instalando dependências para Poetry.

Antes de começar

Você pode usar o SDK do Databricks para Python de dentro de um notebook do Databricks ou de sua máquina de desenvolvimento local.

Antes de começar a usar o SDK do Databricks para Python em sua máquina de desenvolvimento deve ter:

  • Autenticação do Databricks configurada.

  • Python 3.8 ou superior instalado. Para automatizar o Databricks compute recurso, o Databricks recomenda que o senhor tenha as versões principais e secundárias do Python instaladas que correspondam àquelas instaladas no seu Databricks compute recurso de destino. Os exemplos deste artigo baseiam-se na automação do clusters com o Databricks Runtime 13.3 LTS, que tem o Python 3.10 instalado. Para obter a versão correta, consulte Databricks Runtime notas sobre as versões e a compatibilidade com a versão cluster's Databricks Runtime.

  • A Databricks recomenda que você crie e ative um ambiente virtual Python para cada projeto de código Python usado com o SDK do Databricks para Python. Os ambientes virtuais Python ajudam a garantir que o seu projeto de código está a utilizar versões compatíveis de pacotes Python e Python (neste caso, o pacote Databricks SDK para Python). Este artigo explica como usar venv ou Potetry para ambientes virtuais Python.

Crie um ambiente virtual Python com venv

  1. Do seu terminal definido para o diretório raiz do seu projeto de código Python, execute o seguinte comando. Este comando instrui venv a usar o Python 3.10 para o ambiente virtual e, em seguida, cria os arquivos de suporte do ambiente virtual em um diretório oculto chamado .venv no diretório raiz do seu projeto de código Python.

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

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

  2. Utilize o venv para ativar o ambiente virtual. Consulte a documentação do venv para obter o comando correto a ser usado, com base no seu sistema operacional e tipo de terminal. Por exemplo, no macOS executando zsh:

    source ./.venv/bin/activate

    Você saberá que o ambiente virtual está ativado quando o nome do ambiente virtual (por exemplo, .venv) for exibido entre parênteses logo antes do prompt do terminal.

    Para desativar o ambiente virtual a qualquer momento, execute o comando deactivate.

    Você saberá que seu ambiente virtual será desativado quando o nome do ambiente virtual não for mais exibido entre parênteses antes do prompt do terminal.

Avance para Começar com o SDK do Databricks para Python.

Crie um ambiente virtual com Poetry a

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

  2. Do seu terminal definido para o diretório raiz do seu projeto de código Python, execute o seguinte comando para instruir poetry a inicializar seu projeto de código Python para Poetry.

    poetry init

  3. Poetry exibe vários prompts para você completar. Nenhum desses prompts é específico do SDK do Databricks para Python. 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. Com seu terminal ainda configurado para o diretório raiz do seu projeto de código Python, execute o seguinte comando. Este comando instrui poetry a ler o arquivo pyproject.toml , instalar e resolver dependências, criar um arquivo poetry.lock para bloquear as dependências e, finalmente, criar um ambiente virtual.

    poetry install

  6. Do seu terminal definido para o diretório raiz do seu projeto de código Python, execute o seguinte comando para instruir poetry para ativar o ambiente virtual e entrar no shell.

    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.

    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.

Introdução ao SDK do Databricks para Python

Esta seção descreve como começar a usar o SDK do Databricks para Python em sua máquina de desenvolvimento local. Para usar o SDK do Databricks para Python em um Notebook do Databricks, avance para Usar o SDK do Databricks para Python em um Notebookdo Databricks.

  1. Na sua máquina de desenvolvimento com autenticação Databricks configurada, Python já instalado, e o seu ambiente virtual Python já ativado, instale o pacote databricks-sdk (e as suas dependências) do Python Package Index (PyPI), da seguinte forma:

    Use pip para instalar o pacote databricks-sdk . (Em alguns sistemas, pode ser necessário substituir pip3 por pip, aqui e por toda parte.)

    pip3 install databricks-sdk

    poetry add databricks-sdk

    Para instalar uma versão específica do pacote databricks-sdk enquanto o SDK do Databricks para Python estiver na versão Beta, consulte a história de lançamento do pacote. Por exemplo, para instalar a versão 0.1.6:

    pip3 install databricks-sdk==0.1.6

    poetry add databricks-sdk==0.1.6

    Dica

    Para atualizar uma instalação existente do pacote Databricks SDK for Python para a versão mais recente, execute o seguinte comando:

    pip3 install --upgrade databricks-sdk

    poetry add databricks-sdk@latest

    Para mostrar o Version atual do pacote Databricks SDK para Python e outros detalhes, execute o seguinte comando:

    pip3 show databricks-sdk

    poetry show databricks-sdk

  2. Em seu ambiente virtual do Python, crie um arquivo de código do Python que importa o SDK do Databricks para Python. O exemplo a seguir, em um arquivo chamado main.py com o seguinte conteúdo, simplesmente lista todos os clusters em seu workspace do Databricks:

    from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)

  3. Execute seu arquivo de código Python, assumindo um arquivo chamado main.py, executando o comando python :

    python3.10 main.py

    Se você estiver no shell do ambiente virtual:

    python3.10 main.py

    Se você não estiver no shell do ambiente virtual:

    poetry run python3.10 main.py

    Observação

    Ao não definir nenhum argumento na chamada anterior para w = WorkspaceClient(), o Databricks SDK para Python usa seu processo default para tentar executar a autenticação do Databricks. Para substituir esse comportamento default , consulte a seção de autenticação a seguir.

Autentique o SDK do Databricks para Python com sua conta ou workspace do Databricks

Esta seção descreve como autenticar o SDK do Databricks para Python da sua máquina de desenvolvimento local para sua account ou workspace do Databricks. Para autenticar o SDK do Databricks para Python em um Notebook do Databricks, avance para Usar o SDK do Databricks para Python em um Notebookdo Databricks.

O Databricks SDK para Python 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 ajuda a tornar 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. Para obter mais informações, incluindo exemplos de código mais completos em Python, consulte Autenticação unificada do cliente Databricks.

Alguns dos padrões de codificação disponíveis para inicializar a autenticação Databricks com o SDK do Databricks para Python incluem:

  • Use a autenticação padrão do Databricks seguindo um destes procedimentos:

    • Crie ou identifique um perfil de configuração personalizado do Databricks com os campos obrigatórios para o tipo de autenticação do Databricks de destino. Em seguida, defina a variável de ambiente DATABRICKS_CONFIG_PROFILE com o nome do perfil de configuração personalizado.

    • Defina as variáveis de ambiente necessárias para o tipo de autenticação do Databricks de destino.

    Em seguida, instancie, por exemplo, um objeto WorkspaceClient com autenticação default do Databricks da seguinte maneira:

    from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

  • Embora seja possível codificar diretamente os campos necessários, não é aconselhável, pois isso pode expor informações confidenciais em seu código, como tokens de acesso pessoal da Databricks.O exemplo a seguir codifica o host do Databricks e valores de token de acesso para autenticação de token do Databricks:

    from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host  = 'https://...',
  token = '...'
)
# ...

Consulte também Autenticação na documentação do SDK do Databricks para Python.

Use o SDK do Databricks para Python em um Notebookdo Databricks

O senhor pode chamar Databricks SDK para a funcionalidade Python de um Databricks Notebook que tenha um Databricks cluster anexado com o Databricks SDK para Python instalado. O Databricks SDK para Python já está instalado em todos os Databricks clusters que usam Databricks Runtime 13.3 LTS ou acima. Para Databricks clusters que usam Databricks Runtime 12.2 LTS e abaixo, o senhor deve instalar primeiro o Databricks SDK para Python. Consulte o passo 1: Instalar ou atualizar o Databricks SDK para Python.

Para ver o número da versão do Databricks SDK for Python que está instalado em default para uma versão específica do Databricks Runtime, consulte a seção "Installed Python biblioteca" das notas sobre a versão do Databricks Runtime para essa versão do Databricks Runtime.

O Databricks SDK para Python 0.6.0 e acima usa a autenticação default Databricks Notebook. default A autenticação do Databricks Notebook se baseia em um Databricks pessoal temporário access token que o Databricks gera automaticamente em segundo plano para seu próprio uso. O Databricks exclui esses tokens temporários depois que o site Notebook para de funcionar.

Importante

a autenticação dodefault Databricks funciona apenas no Notebook clustersnó do driver dos e não em nenhum dos clusters worker nós ou executor dos .

Databricks Runtime 13.3 LTS e acima suportam default Databricks Notebook autenticação com Databricks SDK para Python 0.1.7 ou acima instalado. Databricks Runtime 10.4 LTS e acima suporta default Databricks Notebook autenticação com Databricks SDK para Python 0.1.10 ou acima instalado. No entanto, o site Databricks recomenda que o senhor instale ou atualize para Databricks SDK para Python 0.6.0 ou acima para obter compatibilidade máxima com default Databricks Notebook autenticação, independentemente da versão Databricks Runtime.

O senhor deve instalar ou atualizar o Databricks SDK for Python nos clusters do Databricks se quiser chamar as APIs de nível do Databricks accountou se quiser usar um tipo de autenticação do Databricks diferente da autenticação do default Databricks Notebook, conforme a seguir:

Tipo de autenticação

Databricks SDK para versões do Python

Autenticação OAuth máquina a máquina (M2M)

Todas as versões

Autenticação OAuth de usuário para máquina (U2M)

0.1.9 e acima

Databricks personal access token authentication

Todas as versões

Autenticação básica (legado) (não recomendada na produção)

Todas as versões

A autenticação do Databricks Notebook não funciona com perfis de configuração do Databricks.

o passo 1: Instalar ou atualizar o Databricks SDK para Python

  1. O Databricks Python Notebook pode usar o Databricks SDK for Python como qualquer outra biblioteca Python. Para instalar ou atualizar a biblioteca Databricks SDK for Python nos clusters Databricks anexados, execute o comando %pip magic em uma célula Notebook da seguinte forma:

    %pip install databricks-sdk --upgrade

  2. Depois de executar o comando mágico %pip, o senhor deve reiniciar o Python para que a biblioteca instalada ou atualizada fique disponível para o Notebook. Para fazer isso, execute o seguinte comando em uma célula Notebook imediatamente após a célula com o comando mágico %pip:

    dbutils.library.restartPython()

  3. Para exibir a versão instalada do Databricks SDK for Python, execute o seguinte comando em uma célula Notebook:

    %pip show databricks-sdk | grep -oP '(?<=Version: )\S+'

o passo 2: execute seu código

Em suas células Notebook, crie um código Python que importe e, em seguida, chame o Databricks SDK for Python. O exemplo a seguir usa a autenticação default Databricks Notebook para listar todos os clusters em seu Databricks workspace:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for c in w.clusters.list():
  print(c.cluster_name)

Quando você executa essa célula, aparece uma lista dos nomes de todos os clusters disponíveis no seu workspace do Databricks.

Para usar um tipo de autenticação Databricks diferente, consulte Tipos de autenticação Databricks compatíveis e clique no link correspondente para obter detalhes técnicos adicionais.

Use o Databricks Utilities

Você pode chamar a referência do Databricks russas (dbutils) do Databricks SDK para código Python em execução em sua máquina de desenvolvimento local ou de dentro de um Databricks Notebook.

  • Na sua máquina de desenvolvimento local, o Databricks russas tem acesso apenas aos grupos de comando dbutils.fs, dbutils.secrets, dbutils.widgets e dbutils.jobs .

  • Em um notebook Databricks conectado a um cluster Databricks, o Databricks Utilities tem acesso a todos os grupos de comandos disponíveis do Databricks Utilities, não apenas dbutils.fs, dbutils.secrets e dbutils.widgets. Além disso, o grupo decomandos dbutils.notebook está limitado a apenas dois níveis de comandos, por exemplo dbutils.notebook.run ou dbutils.notebook.exit.

Para chamar os utilitários do Databricks a partir de sua máquina de desenvolvimento local ou de um Databricks Notebook, use dbutils dentro de WorkspaceClient. Este exemplo de código usa a autenticação default Databricks Notebook para chamar dbutils dentro de WorkspaceClient para listar os caminhos de todos os objetos no DBFS root do workspace.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
d = w.dbutils.fs.ls('/')

for f in d:
  print(f.path)

Como alternativa, o senhor pode ligar diretamente para dbutils. No entanto, o senhor está limitado a usar somente a autenticação default Databricks Notebook. Este exemplo de código chama dbutils diretamente para listar todos os objetos em DBFS root do site workspace.

from databricks.sdk.runtime import *

d = dbutils.fs.ls('/')

for f in d:
  print(f.path)

Você não pode usar dbutils sozinho ou dentro de WorkspaceClient para acessar volumes do Unity Catalog . Em vez disso, use files dentro de WorkspaceClient. Este exemplo de código chama files em WorkspaceClient para imprimir o conteúdo do arquivo especificado no volume especificado.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

resp = w.files.download('/Volumes/main/default/my-volume/sales.csv')
print(str(resp.contents.read(), encoding='utf-8'))

Consulte também Interação com dbutils.

Exemplos de código

Os exemplos de código a seguir demonstram como usar o Databricks SDK for Python para criar e excluir clusters, executar trabalhos e listar grupos de nível account. Esses exemplos de código usam a autenticação default Databricks Notebook. Para obter detalhes sobre a autenticação do default Databricks Notebook, consulte Use o Databricks SDK for Python a partir de um Databricks Notebook. Para obter detalhes sobre a autenticação default fora do Notebook, consulte Autenticar o Databricks SDK para Python com seu Databricks account ou workspace.

Para obter exemplos de código adicionais, consulte os exemplos no repositório Databricks SDK para Python no GitHub. Veja também:

Criar um cluster

Este exemplo de código cria um cluster com a versão especificada do Databricks Runtime e o tipo de nó de cluster. Este cluster tem um worker e será encerrado automaticamente após 15 minutos de inatividade.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

print("Attempting to create cluster. Please wait...")

c = w.clusters.create_and_wait(
  cluster_name             = 'my-cluster',
  spark_version            = '12.2.x-scala2.12',
  node_type_id             = 'i3.xlarge',
  autotermination_minutes = 15,
  num_workers              = 1
)

print(f"The cluster is now ready at " \
      f"{w.config.host}#setting/clusters/{c.cluster_id}/configuration\n")

Excluir permanentemente um cluster

Este exemplo de código exclui permanentemente o cluster com o ID de cluster especificado do workspace.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

c_id = input('ID of cluster to delete (for example, 1234-567890-ab123cd4): ')

w.clusters.permanent_delete(cluster_id = c_id)

Crie um job

Este exemplo de código cria um trabalho do Databricks que executa o notebook especificado no cluster especificado. Conforme o código é executado, ele obtém o caminho do notebook existente, o ID do cluster existente e as configurações de trabalho relacionadas do usuário no terminal.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import Task, NotebookTask, Source

w = WorkspaceClient()

job_name            = input("Some short name for the job (for example, my-job): ")
description         = input("Some short description for the job (for example, My job): ")
existing_cluster_id = input("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4): ")
notebook_path       = input("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook): ")
task_key            = input("Some key to apply to the job's tasks (for example, my-key): ")

print("Attempting to create the job. Please wait...\n")

j = w.jobs.create(
  name = job_name,
  tasks = [
    Task(
      description = description,
      existing_cluster_id = existing_cluster_id,
      notebook_task = NotebookTask(
        base_parameters = dict(""),
        notebook_path = notebook_path,
        source = Source("WORKSPACE")
      ),
      task_key = task_key
    )
  ]
)

print(f"View the job at {w.config.host}/#job/{j.job_id}\n")

Crie um Job que use serverless compute

Visualização

serverless compute O fluxo de trabalho está em Public Preview. Para obter informações sobre elegibilidade e habilitação, consulte Enable serverless compute public preview.

O exemplo a seguir cria um Job que usa serverless compute para fluxo de trabalho:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.jobs import NotebookTask, Source, Task

w = WorkspaceClient()

j = w.jobs.create(
  name = "My Serverless Job",
  tasks = [
    Task(
      notebook_task = NotebookTask(
      notebook_path = "/Users/user@databricks.com/MyNotebook",
      source = Source("WORKSPACE")
      ),
      task_key = "MyTask",
   )
  ]
)

Listar grupos em nível de conta

Este exemplo de código lista os nomes de exibição de todos os grupos disponíveis na conta Databricks.

from databricks.sdk import AccountClient

a = AccountClient()

for g in a.groups.list():
  print(g.display_name)

Testes

Para testar seu código, use estruturas de teste Python, como o pytest. Para testar seu código em condições simuladas sem chamar o endpoint Databricks REST API ou alterar o estado de sua conta ou espaço de trabalho Databricks, use a biblioteca de simulação Python, como unittest.mock.

Por exemplo, dado o seguinte arquivo chamado helpers.py contendo uma função create_cluster que retorna informações sobre o novo cluster:

# helpers.py

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.compute import ClusterDetails

def create_cluster(
  w: WorkspaceClient,
  cluster_name:            str,
  spark_version:           str,
  node_type_id:            str,
  autotermination_minutes: int,
  num_workers:             int
) -> ClusterDetails:
  response = w.clusters.create(
    cluster_name            = cluster_name,
    spark_version           = spark_version,
    node_type_id            = node_type_id,
    autotermination_minutes = autotermination_minutes,
    num_workers             = num_workers
  )
  return response

E dado o seguinte arquivo chamado main.py que chama a função create_cluster:

# main.py

from databricks.sdk import WorkspaceClient
from helpers import *

w = WorkspaceClient()

# Replace <spark-version> with the target Spark version string.
# Replace <node-type-id> with the target node type string.
response = create_cluster(
  w = w,
  cluster_name            = 'Test Cluster',
  spark_version           = '<spark-version>',
  node_type_id            = '<node-type-id>',
  autotermination_minutes = 15,
  num_workers             = 1
)

print(response.cluster_id)

O arquivo a seguir, denominado test_helpers.py, testa se a função create_cluster retorna a resposta esperada. Em vez de criar um cluster no destino workspace, esse teste simula um objeto WorkspaceClient, define as configurações do objeto simulado e, em seguida, passa o objeto simulado para a função create_cluster. Em seguida, o teste verifica se a função retorna a ID esperada do novo cluster simulado.

# test_helpers.py

from databricks.sdk import WorkspaceClient
from helpers import *
from unittest.mock import create_autospec # Included with the Python standard library.

def test_create_cluster():
  # Create a mock WorkspaceClient.
  mock_workspace_client = create_autospec(WorkspaceClient)

  # Set the mock WorkspaceClient's clusters.create().cluster_id value.
  mock_workspace_client.clusters.create.return_value.cluster_id = '123abc'

  # Call the actual function but with the mock WorkspaceClient.
  # Replace <spark-version> with the target Spark version string.
  # Replace <node-type-id> with the target node type string.
  response = create_cluster(
    w = mock_workspace_client,
    cluster_name            = 'Test Cluster',
    spark_version           = '<spark-version>',
    node_type_id            = '<node-type-id>',
    autotermination_minutes = 15,
    num_workers             = 1
  )

  # Assert that the function returned the mocked cluster ID.
  assert response.cluster_id == '123abc'

Para executar esse teste, execute o comando pytest a partir da raiz do projeto de código, que deve produzir resultados de teste semelhantes aos seguintes:

$ pytest
=================== test session starts ====================
platform darwin -- Python 3.12.2, pytest-8.1.1, pluggy-1.4.0
rootdir: <project-rootdir>
collected 1 item

test_helpers.py . [100%]
======================== 1 passed ==========================