Usar o Git com Trabalhos do Lakeflow

As tarefas de trabalho podem fazer checkout 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 do data build tool (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.

Origem do repositório Git versus 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 obtém automaticamente o código-fonte mais recente, se disponível, no momento da execução do trabalho.

O Azure Databricks recomenda referenciar caminhos do workspace em pastas Git apenas para iteração rápida e testes 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ê 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.

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 checkout esparso reduz o tempo de checkout e o uso de recursos em cada execução do trabalho.

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 vantagens, limitações e problemas que podem surgir ao usar o checkout 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 exato do commit
• Impressão digital do padrão de checkout esparso (o conjunto exato de caminhos de 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 (ou após 1 semana).

Cada padrão exclusivo de checkout esparso cria uma impressão digital separada e, portanto, 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. Criar um único padrão de checkout esparso que inclua todas as 20 pastas (por exemplo, uma pasta pai) permite que um único cache seja reutilizado com mais frequência e ofereça melhor desempenho aos seus trabalhos. A desvantagem é um número maior de arquivos no checkout.

Decida se deve usar o checkout esparso

Ative o checkout esparso somente se o seu caso de uso atender aos dois critérios a seguir:

• Tamanho: seu repositório é grande (por exemplo, excede 2.500 arquivos).
• Destino estável: o branch de destino é atualizado com pouca frequência (por exemplo, cerca de um commit por hora ou 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.
• Microdirecionamento: estruture os padrões para que cada um tenha como alvo 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 projetada de importação de Arquivos por Hora taxa de importação. Os limites se aplicam no nível do espaço de trabalho em todas as tarefas e usuários.

Execuções de Trabalhos por Hora × Taxa de Falhas de Cache × Arquivos Importados por Falha

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 a rotatividade de commits

• Faça: direcione os trabalhos para um branch de lançamento estável. Agrupe mesclagens em janelas de lançamento programadas para que várias execuções compartilhem o mesmo commit armazenado em cache.
• Não faça: use checkout esparso com branches atualizados com frequência, 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: remova binários grandes, artefatos gerados e arquivos de dados do controle de versão para reduzir incondicionalmente o tamanho do repositório.
• Não: Deixe de executar trabalhos redundantes com alta frequência. Reduza a frequência de acionamento dos trabalhos que não exigem execução contínua, escalone os agendamentos ou consolide trabalhos que compartilham o mesmo checkout.

Gerencie a rotatividade de commits com um branch de lançamento

Quando os trabalhos têm como destino um branch com mudanças frequentes, como master ou main, o hash do commit muda com frequência, causando falhas de cache em praticamente todas as execuções. Usar um branch de lançamento dedicado, atualizado em uma programação fixa, melhora as taxas de acerto do cache.

Ao direcionar todos os trabalhos para um branch de lançamento atualizado a cada hora, todas as execuções dentro desse período resolvem o mesmo hash de commit 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. Automatize a atualização desse branch para corresponder a master em uma programação fixa, 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 fluxo de trabalho do GitHub Actions automatiza o branch de lançamento por hora.

Etapa 1: faça commit de um arquivo .github/workflows/cut-release-branch.yml 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

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.

Habilite o checkout esparso usando a API Jobs

Para habilitar o checkout esparso, inclua um bloco sparse_checkout dentro de 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.