Usar o Git com Trabalhos do Lakeflow

As tarefas podem realizar o check-out do código-fonte diretamente de um repositório Git remoto.

Os seguintes tipos de tarefa dão suporte a repositórios Git remotos:

• Notebooks
• scripts de Python
• Arquivos SQL
• projetos da ferramenta de build de dados (dbt)

Todas as tarefas de um trabalho precisam referenciar o mesmo commit no repositório remoto. Quando a execução de uma tarefa começa, o Azure Databricks tira um instantâneo do branch ou commit especificado, para que todas as tarefas nessa execução utilizem a mesma versão do código.

Quando você exibe o histórico de execução de uma tarefa que executa o código armazenado em um repositório Git remoto, o painel detalhes da execução da tarefa inclui detalhes do Git, incluindo o SHA de confirmação associado à execução. Confira Ver histórico de execução de tarefas.

Usando uma fonte do repositório Git versus usando pastas Git.

Esta página discute tarefas que podem efetuar pull do código-fonte diretamente de um repositório Git remoto. Os workspaces também dão suporte a um recurso chamado pastas Git, em que uma pasta em seu workspace é sincronizada com um repositório Git. Uma tarefa pode usar uma pasta Git como sua origem. No entanto, você deve gerenciar a sincronização com o repositório. Usar um repositório Git remoto, conforme descrito aqui, automaticamente realiza o pull da nova fonte, se disponível, durante a execução do trabalho.

Azure Databricks recomenda referenciar caminhos de workspace em pastas Git apenas para iteração e teste rápidos durante o desenvolvimento. Para trabalhos de preparo e produção, configure tarefas para fazer referência a um repositório Git remoto.

Configurar um provedor Git para um trabalho

A interface do usuário de trabalhos tem uma caixa de diálogo para configurar um repositório Git remoto. Essa caixa de diálogo pode ser acessada no painel Detalhes do trabalho no título do Git ou em qualquer tarefa configurada para usar um provedor Git. Para acessar a caixa de diálogo, clique em Adicionar configurações do Git no painel Detalhes do trabalho .

Na caixa de diálogo Git (rotulada como Informações do Git, se acessadas durante a configuração da tarefa), insira os seguintes detalhes:

• URL do repositório Git.
• Selecione seu provedor Git na lista suspensa.
• No campo Referência do Git, insira o identificador de um branch, tag ou commit que corresponda à versão do código-fonte que você deseja executar.
• Selecione branch, tag ou commit na lista suspensa.

Você deve especificar apenas um dos seguintes:

• branch: o nome do branch, por exemplo, main.
• tag: o nome da etiqueta, por exemplo, release-1.0.0.
• commit: o hash de um commit específico, por exemplo, e0056d01.

Quando você visualiza o histórico de execução de uma tarefa que executa o código armazenado em um repositório Git remoto, o painel Detalhes da execução da tarefa inclui detalhes do Git, incluindo o SHA de confirmação associado à execução. Confira Ver histórico de execução de tarefas.

Checkout esparso para repositórios grandes

Para repositórios grandes, você pode usar o checkout esparso para importar apenas diretórios específicos em vez do repositório completo. O check-out esparso reduz o tempo de check-out e o uso de recursos por execução de tarefa.

No entanto, a configuração inadequada pode causar fragmentação de cache, o que degrada os tempos de execução em todo o workspace. Esta seção descreve as compensações e problemas que podem surgir ao usar o check-out esparso.

Como o Azure Databricks armazena em cache os checkouts do repositório

Azure Databricks armazena em cache cada check-out do Git com base em quatro valores:

• Workspace
• URL do repositório
• Hash de confirmação exato
• Impressão digital do padrão de checkout esparso (o conjunto exato de caminhos das pastas)

Qualquer execução de trabalho que corresponda a todos os quatro critérios reutiliza uma entrada de cache, que permanece válida por até uma semana. Por exemplo, se você tiver três trabalhos diferentes e todos eles tiverem os mesmos critérios, eles usarão o mesmo cache no repositório até que haja uma nova confirmação (após 1 semana).

Cada padrão de checkout esparso exclusivo cria uma impressão digital separada e, consequentemente, uma entrada de cache distinta. Se 20 usuários adicionarem uma pasta personalizada ao padrão, o sistema criará 20 chaves de cache distintas e importará a árvore de pastas compartilhadas 20 vezes , multiplicando a carga em seu workspace. A criação de um único padrão de check-out esparso que inclua todas as 20 pastas, como, por exemplo, uma pasta principal, permite que um único cache seja utilizado com mais frequência e otimize o desempenho das suas tarefas. A compensação é um número maior de arquivos em seu checkout.

Decida se deseja usar o checkout esparso

Habilite apenas o checkout esparso se o caso de uso atender aos dois critérios a seguir:

• Tamanho: seu repositório é grande (por exemplo, excede 2.500 arquivos).
• Stable targeting: o branch de destino é atualizado com pouca frequência (por exemplo, aproximadamente um commit por hora, ou até menos). Evite branches que mudam rapidamente devido a fluxos de trabalho automatizados de CI/CD.

Se você usar o checkout esparso, sua organização também deverá adotar uma ou ambas as seguintes estratégias de padrão:

• Padronização: use três ou menos padrões de check-out compartilhados em toda a organização para maximizar as ocorrências de cache.
• Micro-direcionamento: padrões de estrutura para que cada um tenha como destino um pequeno número de arquivos. Para obter o melhor desempenho, mantenha menos de 200 arquivos.

Isso pode ajudar a minimizar sua taxa de importação.

Calcular sua taxa de importação

Antes de habilitar o checkout esparso, estime a taxa de importação projetada de Arquivos por Hora. Os limites se aplicam no nível do espaço de trabalho em todas as tarefas e usuários.

Arquivos por hora = Execuções de trabalho por hora × taxa de erro de cache × arquivos importados por erro

Exemplo: 180 execuções/hora × 10% taxa de erro × 6.000 arquivos/erro = 108.000 arquivos/hora

Compare o resultado com estes limites:

Práticas recomendadas

Padronizar padrões

• Faça: publicar três ou menos padrões esparsos aprovados por repositório. Os padrões compartilhados consolidam as cargas e maximizam os acessos ao cache.
• Não permitir padrões personalizados por equipe. Até mesmo uma pasta extra cria uma nova entrada de cache e dispara uma nova importação completa.

Gerenciar o volume de alterações em commits

• Executar: direcionar tarefas para uma ramificação de versão estável. Lotes mesclam-se em janelas de lançamento programadas para que várias execuções compartilhem o mesmo commit em cache.
• Não: use checkouts esparsos com ramificações frequentemente atualizadas como master ou main. Como o cache é baseado no hash de confirmação exato, cada nova confirmação invalida o cache e causa uma nova importação completa para cada execução de trabalho.

Gerenciar carga

• Faça: remover binários grandes, artefatos gerados e arquivos de dados do controle do código-fonte para reduzir o tamanho do repositório incondicionalmente.
• Não: Deixe de executar trabalhos redundantes com alta frequência. Reduzir a frequência de acionamento para trabalhos que não exigem execução contínua, escalar agendamentos ou consolidar trabalhos que compartilham o mesmo checkout.

Gerenciar o churn de commit com uma ramificação de lançamento

Quando os trabalhos se destinam a um branch de movimentação rápida como master ou main, o hash de confirmação é alterado com frequência, causando erros de cache em quase todas as execuções. O uso de um branch de versão dedicado que é atualizado em um cronograma fixo melhora as taxas de acertos no cache.

Apontando todos os trabalhos para um branch de lançamento por hora, todas as execuções dentro dessa hora são resolvidas para o mesmo hash de confirmação e compartilham a mesma entrada de cache.

Para configurar um branch de lançamento:

1. Crie um branch de longa duração (por exemplo, release-candidate) em seu repositório Git.
2. Automatizar a atualização desse branch para coincidir com master em um agendamento fixo, como no início de cada hora.
3. Configure seus jobs com suporte Git para usar release-candidate como sua referência Git de destino.

Examine estas compensações antes de implementar:

Exemplo: automatizar com GitHub Actions

O seguinte fluxo de trabalho do GitHub Actions automatiza a criação de uma ramificação de versão a cada hora.

Etapa 1: confirmar um .github/workflows/cut-release-branch.yml arquivo em seu repositório:

name: Cut Hourly Release Candidate

on:
  schedule:
    - cron: '0 * * * *'
  workflow_dispatch:

jobs:
  update-branch:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout main branch
        uses: actions/checkout@v4
        with:
          ref: main
          fetch-depth: 0

      - name: Update release-candidate branch
        run: |
          git push origin HEAD:release-candidate --force

Step 2: dispare manualmente a Ação GitHub para verificar se o branch release-candidate foi criado.

Etapa 3: atualize seus trabalhos existentes para usar release-candidate como referência git de destino.

Habilitar o check-out esparso usando a API de Trabalhos

Para habilitar o check-out esparso, inclua um sparse_checkout bloco dentro git_source ao criar ou atualizar um trabalho:

{
  "git_source": {
    "git_url": "https://github.com/example/my-repo",
    "git_provider": "gitHub",
    "git_branch": "release-candidate",
    "sparse_checkout": {
      "patterns": ["src/models", "src/utils"]
    }
  }
}

Cada cadeia de caracteres patterns é um caminho de diretório relativo à raiz do repositório. Todos os arquivos em cada diretório especificado são incluídos no check-out.