Utilize o Git com tarefas do Lakeflow

As tarefas de trabalho podem consultar código-fonte diretamente de um repositório Git remoto.

Os seguintes tipos de tarefas suportam repositórios Git remotos:

• Notebooks
• Python scripts
• Arquivos SQL
• Projetos da Ferramenta de Construção de Dados (DBT)

Todas as tarefas num processo devem fazer referência ao mesmo commit no repositório remoto. Quando uma execução de trabalho começa, o Azure Databricks tira um snapshot do branch ou commit especificado, de modo que todas as tarefas dessa execução utilizam a mesma versão do código.

Quando visualiza o histórico de execução de uma tarefa que executa código armazenado num repositório Git remoto, o painel de detalhes de execução da Tarefa inclui detalhes Git, incluindo o SHA de commit associado à execução. Consulte Ver histórico de execução de tarefas.

Usar um código-fonte de repositório Git vs usar diretórios Git.

Esta página discute tarefas que podem extrair código-fonte diretamente de um repositório Git remoto. Os espaços de trabalho também suportam uma funcionalidade chamada pastas Git, onde uma pasta no seu espaço de trabalho é sincronizada com um repositório Git. Uma tarefa pode usar uma pasta Git como fonte. No entanto, tens de gerir a sincronização com o repositório. Usar um repositório Git remoto, como descrito aqui, executa automaticamente novo código fonte, se disponível, durante a execução do trabalho.

O Azure Databricks recomenda referenciar caminhos de workspace em pastas Git apenas para iteração rápida e testes durante o desenvolvimento. Para tarefas de staging e produção, configure as tarefas para referenciarem um repositório Git remoto em vez disso.

Configure um fornecedor Git para uma tarefa

A interface do usuário de trabalhos tem uma caixa de diálogo para configurar um repositório Git remoto. Este diálogo é acessível a partir do painel de detalhes do trabalho sob o cabeçalho Git , ou em qualquer tarefa configurada para usar um fornecedor Git. Para aceder ao diálogo, clique em Adicionar definições do Git no painel de detalhes do trabalho .

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

• A URL do repositório Git.
• Selecione o seu fornecedor Git na lista suspensa.
• No campo de referência do Git, insira o identificador de uma ramificação, tag ou confirmação que corresponda à versão do código-fonte que você deseja executar.
• Selecione branch, tag ou commit no menu suspenso.

Deve especificar apenas um dos seguintes pontos:

• ramo: O nome do ramo, por exemplo, main.
• tag: o nome da tag, por exemplo, release-1.0.0.
• commit: o hash de uma confirmação específica, por exemplo, e0056d01.

Quando você visualiza o histórico de execução de uma tarefa que executa 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. Consulte Ver histórico de execução de tarefas.

Verificação esparsa para repositórios grandes

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

No entanto, uma configuração inadequada pode causar fragmentação da cache, o que degrada os tempos de execução em todo o seu espaço de trabalho. Esta secção descreve as compensações e problemas que podem surgir ao utilizar o checkout sparse.

Como Azure Databricks armazena em cache as verificações de repositórios

O Azure Databricks armazena em cache cada checkout Git com base em quatro valores:

• Workspace
• URL do repositório
• Hash exato de commit
• Impressão digital do padrão de checkout esparso (o conjunto exato de caminhos de pasta)

Qualquer trabalho executado que cumpra os quatro critérios reutiliza uma entrada de cache, que permanece válida até uma semana. Por exemplo, se tiver 3 tarefas diferentes e todas tiverem os mesmos critérios, usam a mesma cache no repositório até haver um novo commit (ou após 1 semana).

Cada padrão único de checkout esparso cria uma impressão digital separada e, portanto, uma entrada de cache separada. Se 20 utilizadores adicionarem cada um uma pasta personalizada ao seu padrão, o sistema cria 20 chaves de cache distintas e importa a árvore de pastas partilhadas 20 vezes — multiplicando a carga no seu espaço de trabalho. Criar um único padrão de checkout esparso que inclua todas as 20 pastas (por exemplo, uma pasta pai) permite que uma única cache funcione com mais frequência e tenha melhor desempenho nos seus trabalhos. A desvantagem é um maior número de ficheiros no checkout.

Avalie se deve usar a opção de checkout esparso

Só ative o sparse checkout se o seu caso de uso cumprir ambos os seguintes critérios:

• Tamanho: O seu repositório é grande (por exemplo, ultrapassa os 2.500 ficheiros).
• Direcionamento estável: Ramo alvo é atualizado raramente (por exemplo, cerca de um commit por hora ou menos). Evite ramificações que mudam rapidamente devido a fluxos de trabalho automatizados de CI/CD.

Se usar o "sparse checkout", a sua organização também deverá adotar uma ou ambas as seguintes estratégias de padrões:

• Padronização: Use três ou menos padrões de checkout partilhados em toda a organização para maximizar os acessos à cache.
• Micro-targeting: Estruture os padrões para que cada um foque num pequeno número de ficheiros. Para um melhor desempenho, procure ter menos de 200 ficheiros.

Estas podem ajudar a minimizar a taxa de importação.

Calcule a sua taxa de importação

Antes de ativar o checkout esparso, estime a sua taxa de importação de ficheiros por hora prevista. Os limites aplicam-se ao nível do espaço de trabalho em todos os trabalhos e utilizadores.

Ficheiros por Hora = Tarefas Executadas por Hora × Taxa de Falhas de Cache × Ficheiros Importados por Falha

Exemplo: 180 corridas/hora × 10% taxa de falha × 6.000 ficheiros/falha = 108.000 ficheiros/hora

Compare o seu resultado com estes limiares:

Melhores práticas

Padronizar padrões

• Fazer: Publicar três ou menos padrões esparsos aprovados por repositório. Padrões partilhados consolidam a carga e maximizam os impactos na cache.
• Não: Permitir padrões personalizados por equipa. Mesmo uma pasta extra cria uma nova entrada de cache e desencadeia uma reimportação completa.

Gerir a frequência de mudanças dos commits

• Fazer: Direcionar as tarefas para um branch de lançamento estável. Lote mescla-se em janelas de lançamento programadas para que várias execuções possam partilhar o mesmo commit em cache.
• Não: Usar checkouts esparsos com ramificações atualizadas frequentemente como master ou main. Como a cache é baseada no hash de commit exato, cada novo commit invalida a cache e causa uma reimportação completa para cada execução de trabalho.

Gerir a carga

• Recomenda-se: Remova binários grandes, artefactos gerados e ficheiros de dados do controlo de código-fonte para reduzir o tamanho do repositório, incondicionalmente.
• Não: Deixar trabalhos redundantes em execução com alta frequência. Menor frequência de gatilhos para trabalhos que não exigem execução contínua, escalonar agendamentos ou consolidar trabalhos que partilham o mesmo checkout.

Gerir as alterações frequentes de commit com um ramo de lançamento

Quando os jobs visam um ramo de rápida evolução como master ou main, o hash de commit muda frequentemente, causando falhas na cache em quase todas as execuções. Usar um ramo de lançamento dedicado que atualiza num calendário fixo aumenta as taxas de acerto na cache.

Ao direcionar todas as tarefas para um ramo de lançamento horário, todas as execuções nessa hora correspondem ao mesmo código de confirmação e partilham o mesmo registro de cache.

Para configurar uma ramificação de lançamento:

1. Crie um ramo duradouro (por exemplo, release-candidate) no seu repositório Git.
2. Automatize a atualização deste ramo para sincronizar com master num horário fixo, exatamente no início de cada hora.
3. Configura os teus jobs apoiados pelo Git para usar release-candidate como a referência Git de destino.

Revise estas compensações antes de implementar:

Exemplo: automatizar com GitHub Actions

O seguinte fluxo de trabalho do GitHub Actions automatiza a criação de um novo ramo de lançamento a cada hora.

Passo 1: Comprometa um .github/workflows/cut-release-branch.yml ficheiro no 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

Passo 2: Acione manualmente a Ação GitHub para verificar se o ramo release-candidate foi criado.

Passo 3: Atualize os seus empregos existentes para usar release-candidate como referência Git alvo.

Ative o "sparse checkout" usando a Jobs API

Para permitir o checkout esparso, inclua sparse_checkout um bloco dentro de git_source ao criar ou atualizar uma tarefa:

{
  "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 string em patterns é um caminho de diretório relativo à raiz do repositório. Todos os ficheiros dentro de cada diretório especificado estão incluídos no checkout.