Desenvolver pipelines declarativos do Lakeflow Spark com pacotes de ativos do Databricks

Os Pacotes de Ativos do Databricks, também conhecidos simplesmente como pacotes, permitem que você valide, implante e execute programaticamente recursos do Azure Databricks, como o Lakeflow Spark Declarative Pipelines. Veja o que são pacotes de ativos do Databricks?.

Esta página descreve como criar um pacote para gerenciar programaticamente um pipeline. Consulte Pipelines Declarativos do Lakeflow Spark. O pacote é gerado a partir do modelo de pacote padrão para Python dos Pacotes de Ativos do Databricks, que define um pipeline ETL e uma tarefa para executá-lo. Em seguida, você valida, implanta e executa o pipeline implantado em seu workspace do Azure Databricks.

Requisitos

• CLI do Databricks versão 0.276.0 ou superior. Para verificar a versão instalada da CLI do Databricks, execute o comando databricks -v. Para instalar a CLI do Databricks, consulte Instalar ou atualizar a CLI do Databricks.
• uv é necessário para executar testes e instalar dependências para este projeto a partir de um IDE.
• O espaço de trabalho remoto deve ter arquivos de espaço de trabalho habilitados. Veja o que são arquivos de workspace?.
• Um catálogo existente para tabelas no pipeline. Confira Criar catálogos.

(Opcional) Instalar um módulo Python para dar suporte ao desenvolvimento de pipeline local

O Databricks fornece um módulo Python para ajudar no desenvolvimento local do código de Pipelines Declarativos do Lakeflow Spark, fornecendo verificação de sintaxe, preenchimento automático e verificação de tipo de dados enquanto você escreve código em seu IDE.

O módulo Python para desenvolvimento local está disponível no PyPi. Para instalar o módulo, consulte o stub do Python para DLT.

Etapa 1: configurar a autenticação

Primeiro, configure a autenticação entre a CLI do Databricks em seu computador de desenvolvimento e seu workspace do Azure Databricks. Esta página pressupõe que você deseja usar a autenticação U2M (usuário para máquina) do OAuth e um perfil de configuração do Azure Databricks correspondente nomeado DEFAULT para autenticação.

1. Use o CLI do Databricks para iniciar o gerenciamento de tokens OAuth executando localmente o comando a seguir para cada workspace de destino.

   No comando a seguir, substitua <workspace-url> pela URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

2. A CLI do Databricks solicita que você salve as informações inseridas como um perfil de configuração do Azure Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome será substituído pelas informações inseridas. Você pode usar perfis para alternar rapidamente seu contexto de autenticação em vários workspaces.

   Para obter uma lista de quaisquer perfis existentes, em um terminal ou prompt de comando separado, use a CLI do Databricks para executar o comando databricks auth profiles. Para exibir as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

3. No seu navegador da Web, complete as instruções na tela para iniciar sessão no seu workspace do Azure Databricks.

4. Para ver o valor atual do token OAuth de um perfil e o carimbo de data/hora de expiração do token, execute um dos seguintes comandos:

   • databricks auth token --host <workspace-url>
   • databricks auth token -p <profile-name>
   • databricks auth token --host <workspace-url> -p <profile-name>

   Se você tiver vários perfis com o mesmo valor --host, talvez seja necessário especificar as opções --host e -p em conjunto para ajudar a CLI do Databricks a encontrar as informações de token OAuth correspondentes corretas.

Etapa 2: criar o pacote

Inicialize um pacote usando o modelo padrão de projeto de pacote Python.

1. Use seu terminal ou prompt de comando para alternar para um diretório no seu computador de desenvolvimento local que conterá o pacote gerado do modelo.

2. Use a CLI do Databricks para realizar a execução do comando bundle init:

   databricks bundle init
   

3. Para Template to use, deixe o valor padrão default-python pressionando Enter.

4. Para Unique name for this project, deixe o valor padrão de my_project, ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz para esse pacote. Esse diretório raiz é criado no diretório de trabalho atual.

5. Para Include a job that runs a notebook, selecionar no e pressionar Enter. (O notebook de exemplo associado a essa opção não tem nenhum código de pipeline nele.)

6. Para Include an ETL pipeline, deixe o valor padrão yes pressionando Enter. Isso adiciona um código de pipeline de exemplo e uma definição de pipeline.

7. Para Include a stub (sample) Python package, selecionar no e pressionar Enter.

8. Para Use serverless, selecionar yes e pressionar Enter. Isso instrui a CLI do Databricks a configurar seu pacote para ser executado na computação sem servidor.

9. Para Default catalog for any tables created by this project [hive_metastore], insira o nome de um catálogo existente do Unity Catalog.

10. Para Use a personal schema for each user working on this project., selecione yes.

Etapa 3: explorar o pacote

Para visualizar os arquivos gerados pelo modelo, alterne para o diretório raiz do pacote recém-criado. Os arquivos de interesse específico incluem o seguinte:

• databricks.yml: este arquivo especifica o nome programático do pacote, inclui referências aos arquivos do pacote, define variáveis de catálogo e esquema e especifica as configurações para workspaces de destino.
• resources/sample_job.yml e resources/<project-name>_etl_pipeline.yml: esses arquivos definem o trabalho que contém uma tarefa de atualização de pipeline e as configurações do pipeline. Para obter informações sobre configurações de pipeline, consulte pipeline.
• src/: essa pasta contém os arquivos de origem, explorações e transformações do pipeline de exemplo.
• tests/ e fixtures/: essas pastas contêm testes de unidade de exemplo para o pipeline e os fixtures para conjuntos de dados.
• README.md: este arquivo contém informações adicionais sobre como começar e usar este modelo de pacote.

Etapa 4: Validar a configuração do pacote

Agora, verifique se a configuração do pacote é válida.

1. No diretório raiz, use a CLI do Databricks para executar o bundle validate comando:

   databricks bundle validate
   

2. Se um resumo da configuração do pacote for retornado, então a validação foi bem-sucedida. Se algum erro for retornado, corrija-os e repita essa etapa.

Etapa 5: Implantar o pacote no workspace remoto

Em seguida, implante o conjunto de pacotes no espaço de trabalho remoto do Azure Databricks e verifique o pipeline em seu espaço de trabalho.

1. Na raiz do pacote, use a CLI do Databricks para executar o comando bundle deploy.

   databricks bundle deploy --target dev
   

   Observação

   O modelo padrão inclui um trabalho que executa o pipeline todos os dias, mas isso é pausado no modo de implantação dev alvo. Confira Modos de implantação do Pacote de Ativos do Databricks.

2. Confirme se o pacote foi implantado:

   1. Na barra lateral do workspace do Azure Databricks, clique em Workspace.
   2. Clique na pasta Usuários ><your-username>>.bundle e localize o projeto do pacote.

3. Verifique se o seu pipeline foi criado:

   1. Na barra lateral do workspace do Azure Databricks, clique em Jobs & Pipelines.
   2. Opcionalmente, selecione os filtros Pipelines e Owned by me .
   3. Clique em [dev <your-username>] <project-name>_etl.

Se você fizer todas as alterações em seu pacote após esta etapa, deverá repetir as etapas 4 a 5 para verificar se a configuração do pacote ainda é válida e, em seguida, reimplantar o projeto.

Etapa 6: Executar o pipeline implantado

Agora, inicie uma execução do pipeline no seu workspace a partir da linha de comando.

1. No diretório raiz, use a CLI do Databricks para executar o bundle run comando, substituindo <project-name> pelo nome do seu projeto:

   databricks bundle run --target dev <project-name>_etl
   

2. Copie o valor de Update URL que aparece em seu terminal e cole esse valor em seu navegador da Web para abrir seu workspace do Azure Databricks.

3. No workspace do Azure Databricks, depois que a execução do pipeline for concluída com êxito, clique nas exibições materializadas para ver os detalhes de cada exibição.

Se você fizer todas as alterações no pacote após esta etapa, deverá repetir as etapas de 4 a 6 para verificar se a configuração do pacote ainda é válida, reimplantar o projeto e executar o projeto reimplantado.

Etapa 7: Executar testes

Por fim, use pytest para executar testes localmente:

uv run pytest

Etapa 8: Limpar

Nesta etapa, você excluirá o pacote implementado e o pipeline do seu espaço de trabalho.

1. No diretório raiz, use a CLI do Databricks para executar o bundle destroy comando:

   databricks bundle destroy --target dev
   

2. Quando solicitado a destruir permanentemente os recursos, o pipeline e as tabelas e exibições gerenciados pelo pipeline, digite y e pressione Enter.

3. Se você também quiser excluir o pacote do seu computador de desenvolvimento, agora poderá excluir o diretório do projeto local.