Use Git com os trabalhos LakeFlow

A tarefa Job pode obter o código-fonte diretamente de um repositório Git remoto.

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

• cadernos
• Scripts Python
• Arquivos SQL
• Projetos da ferramenta de construção de dados (dbt)

Todas as tarefas em um Job devem fazer referência ao mesmo commit no repositório remoto. Quando a execução de um Job é iniciada, Databricks tira um Snapshot do branch ou commit especificado, para que todas as tarefas nessa execução usem a mesma versão do código.

Ao view a história de execução de uma tarefa cujo código de execução está armazenado em um repositório Git remoto, o painel de detalhes da tarefa inclui detalhes Git , incluindo o SHA commit associado à execução. Veja visualizar tarefa execução história.

nota

A tarefa configurada para usar um repositório Git remoto não pode gravar em arquivos workspace . Essas tarefas devem gravar dados temporários em armazenamento efêmero conectado ao nó do driver e dados persistentes em um volume ou tabela.

Utilizar um repositório Git como fonte versus utilizar pastas Git.

Esta página discute tarefas que podem extrair código-fonte diretamente de um repositório Git remoto. O espaço de trabalho também oferece suporte a um recurso chamado pastasGit, onde uma pasta em seu workspace é sincronizada com um repositório Git . Uma tarefa pode usar uma pasta Git como sua origem. No entanto, você precisa gerenciar a sincronização com o repositório. Utilizar um repositório Git remoto, conforme descrito aqui, baixa automaticamente o novo código-fonte, se disponível, no momento da execução do Job.

Databricks recomenda referenciar caminhos workspace em pastas Git apenas para iteração rápida e testes durante o desenvolvimento. Para tarefas de teste e produção, configure a tarefa para referenciar um repositório Git remoto.

Configure um provedor Git para um Job.

A interface de usuário do Job possui uma caixa de diálogo para configurar um repositório Git remoto. Esta caixa de diálogo pode ser acessada no painel DetalhesJob , na seção Git , ou em qualquer tarefa configurada para usar um provedorGit . Para acessar a caixa de diálogo, clique em Adicionar configurações Git no painel DetalhesJob .

Na caixa de diálogo Git (rótulo Git informação se acessada durante a configuração da tarefa), insira os seguintes detalhes:

• O URL do repositório Git .
• Selecione seu provedor Git na lista suspensa.
• No campo de referênciaGit , 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 no menu suspenso.

Você deve especificar apenas uma das seguintes opções:

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

nota

A caixa de diálogo pode exibir a seguinte mensagem: As credenciaisGit para esta account estão ausentes. Adicione as credenciais . Você precisa configurar um repositório Git remoto antes de usá-lo como referência. Consulte Configurar a integração do Git para pastas do Git.

Ao view a história de execução de uma tarefa cujo código de execução está armazenado em um repositório Git remoto, o painel de detalhes da tarefa inclui detalhes Git , incluindo o SHA commit associado à execução. Veja visualizar tarefa execução história.

Checkout simplificado 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 por execução do Job.

No entanto, uma configuração inadequada pode causar fragmentação do cache, o que degrada os tempos de execução em todo o seu workspace. Esta seção descreve as vantagens e desvantagens e os problemas que podem surgir ao usar o checkout simplificado.

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

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

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

Qualquer execução de tarefa 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 3 trabalhos diferentes, e todos eles tiverem os mesmos critérios, eles usarão o mesmo cache para o repositório até que haja um novo commit (ou após 1 semana).

Cada padrão de checkout esparso e único cria uma impressão digital separada e, portanto, uma entrada de cache separada. Se 20 usuários adicionarem uma pasta personalizada ao seu 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 funcione com mais frequência e tenha melhor desempenho em seu Job. A desvantagem é um número maior de arquivos no seu checkout.

Decida se deve usar o checkout simplificado.

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

• Tamanho : Seu repositório é grande (por exemplo, possui mais de 2.500 arquivos).
• Direcionamento estável : O branch de destino é atualizado com pouca frequência (por exemplo, cerca de um commit por hora ou menos). Evite filiais que mudam rapidamente devido ao fluxo de trabalho automatizado CI/CD .

Se você utiliza o checkout esparso, sua organização também deve adotar uma ou ambas as seguintes estratégias de padronização:

• Padronização : Utilize três ou menos padrões de finalização de compra compartilhados em toda a organização para maximizar o número de acessos ao cache.
• Microsegmentação : Estruture os padrões de forma que cada um tenha como alvo um pequeno número de arquivos. Para obter o melhor desempenho, utilize menos de 200 arquivos.

Essas medidas podem ajudar a minimizar sua taxa de importação.

Calcule sua taxa de importação

Antes de ativar o checkout simplificado, estime sua taxa projetada de importação de arquivos por hora . Existem limites no nível workspace para todos os trabalhos e usuários.

Arquivos por hora = Execução Job por hora × Taxa de falhas de cache × Arquivos importados por falha

Fator	O que o motiva
Execução Job por hora	Frequência de ativação em todos os usuários
Taxa de falhas de cache	Frequência de commits no branch de destino e número de padrões esparsos únicos.
Arquivos importados por Miss	Tamanho total do repositório ou tamanho do subconjunto de checkout esparso

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

Compare seu resultado com esses limites:

Arquivos importados por hora	Impacto esperado workspace
abaixo de 150.000	Operações normais
150.000 – 300.000	Desempenho degradado. Algumas tarefas podem sofrer atrasos ou falhas.
acima de 300.000	Os trabalhos não são concluídos de forma confiável.

Melhores práticas

Padronizar padrões

• Recomendação : Publique no máximo três padrões esparsos aprovados por repositório. Padrões compartilhados consolidam a carga e maximizam os acertos de cache.
• Não permita padrões personalizados por equipe. Mesmo uma única pasta extra cria uma nova entrada no cache e aciona uma reimportação completa.

gerencie a rotatividade commit

• Faça : Direcione o trabalho para uma ramificação de lançamento estável. Os lotes são mesclados em janelas de lançamento agendadas, de modo que várias execuções compartilhem o mesmo commit em cache.
• Não faça : Use checkouts esparsos com branches atualizados frequentemente, como master ou main. Como o cache é baseado no hash exato commit , cada novo commit invalida o cache e causa uma reimportação completa para cada execução do Job.

r/carregar

• Faça o seguinte : Remova arquivos binários grandes, artefatos gerados e arquivos de dados do controle de versão para reduzir o tamanho do repositório incondicionalmente.
• Não deixe tarefas redundantes sendo executadas com alta frequência. Diminua a frequência de acionamento para tarefas que não exigem execução contínua, escalone a programação ou consolide tarefas que compartilham o mesmo checkout.

gerenciar alterações commit com um branch de lançamento

Quando o Job tem como alvo um branch de mudança rápida como master ou main, o hash commit muda frequentemente, causando falhas de cache em quase todas as execuções. Utilizar uma ramificação de lançamento dedicada que seja atualizada em um programador fixo melhora as taxas de acerto de cache.

Ao direcionar todos os trabalhos para um branch de lançamento por hora, todas as execuções dentro dessa hora resultam no mesmo hash commit e compartilham a mesma entrada de cache.

Para configurar uma ramificação 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 deste ramo para corresponder master em um programar fixo, como no início de cada hora.
3. Configure seu Job com suporte Gitpara usar release-candidate como sua referência Git de destino.

Analise essas vantagens e desvantagens antes de implementar:

Consideração	Descrição
atraso de confirmação	Execução de tarefas contra código com até uma hora de atraso master. Aceitável para a maioria das cargas de trabalho em lote, mas pode não ser adequado para trabalhos que exigem o commit mais recente.
Janela de falha	Se a tarefa de correção de lançamento falhar, o branch não será atualizado durante essa hora e a tarefa continuará sendo executada com base no commit anterior. Databricks recomenda configurar alertas para o Job interrompido.

Exemplo: automatize com o GitHub Actions

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

o passo 1 : envie um arquivo .github/workflows/cut-release-branch.yml para seu repositório:

YAML

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

o passo 2 : Acione manualmente o GitHub Actions para verificar se a branch release-candidate foi criada.

o passo 3 : Atualize seu Job existente para usar release-candidate como a referência Git de destino.

Habilite o checkout simplificado usando a API de Tarefas.

Para habilitar o checkout simplificado, inclua um bloco sparse_checkout dentro de git_source ao criar ou atualizar um Job:

JSON

{
  "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 arquivos dentro de cada diretório especificado estão incluídos no checkout.