Usare Git con Lakeflow Jobs

Le attività lavorative possono controllare il codice sorgente direttamente da un repository Git remoto.

I tipi di attività seguenti supportano repository Git remoti:

• Computer portatili
• script di Python
• File SQL
• progetti di data build tool (dbt)

Tutte le attività in un processo devono fare riferimento allo stesso commit nel repository remoto. All'avvio di un'esecuzione di un processo, Azure Databricks crea uno snapshot del ramo o del commit specificato, in modo che tutte le attività in esecuzione usino la stessa versione del codice.

Quando si visualizza la cronologia di esecuzione di un'attività che esegue il codice archiviato in un repository Git remoto, il riquadro Dettagli esecuzione attività include i dettagli git, incluso il commit SHA associato all'esecuzione. Si veda Visualizzare la cronologia di esecuzione dell’attività.

Uso di un'origine del repository Git rispetto all'uso di cartelle Git.

Questa pagina illustra le attività che possono eseguire il pull del codice sorgente direttamente da un repository Git remoto. Le aree di lavoro supportano anche una funzionalità denominata Cartelle Git, in cui una cartella nell'area di lavoro viene sincronizzata con un repository Git. Un'attività può usare una cartella Git come origine. Tuttavia, è necessario gestire la sincronizzazione con il repository. L'uso di un repository Git remoto come descritto qui esegue automaticamente il pull di nuovo codice sorgente, se disponibile, durante l'esecuzione del processo.

Azure Databricks consiglia di fare riferimento ai percorsi dell'area di lavoro nelle cartelle Git solo per l'iterazione e il test rapidi durante lo sviluppo. Per i processi di staging e di produzione, configurare invece le attività per fare riferimento a un repository Git remoto.

Configurare un provider Git per un processo

L'interfaccia utente dei processi include una finestra di dialogo per configurare un repository Git remoto. Questa finestra di dialogo è accessibile dal riquadro Dettagli del processo sotto l'intestazione Git o in qualsiasi attività configurata per l'uso di un provider Git. Per accedere alla finestra di dialogo, fare clic su Aggiungi impostazioni Git nel riquadro Dettagli del processo.

Nella finestra di dialogo Git (etichettata Informazioni su Git se si accede durante la configurazione delle attività), immettere i dettagli seguenti:

• L'URL del repository Git.
• Selezionare il provider Git dall'elenco a discesa.
• Nel campo Riferimento Git immettere l'identificatore per un ramo, un tag o un commit che corrisponde alla versione del codice sorgente da eseguire.
• Selezionare branch, tag o commit dall'elenco a discesa.

È necessario specificare solo uno dei seguenti elementi:

• branch: il nome del ramo, ad esempio main.
• tag: il nome del tag, release-1.0.0ad esempio .
• commit: l’hash di un commit specifico, ad esempio e0056d01.

Quando si visualizza la cronologia di esecuzione di un'attività che esegue il codice archiviato in un repository Git remoto, il pannello Dettagli esecuzione attività include i dettagli Git, incluso il commit SHA associato all'esecuzione. Si veda Visualizzare la cronologia di esecuzione dell’attività.

Checkout parziale per repository di grandi dimensioni

Per i repository di grandi dimensioni, è possibile usare il checkout sparse per importare solo directory specifiche anziché il repository completo. L'utilizzo del sparse checkout riduce il tempo di estrazione e l'utilizzo delle risorse per ogni esecuzione del job.

Tuttavia, la configurazione non corretta può causare frammentazione della cache, che degrada i tempi di esecuzione nell'intera area di lavoro. Questa sezione descrive i compromessi e i problemi che possono verificarsi quando si usa il checkout sparse.

Come Azure Databricks memorizza nella cache i checkout dei repository

Azure Databricks memorizza nella cache ogni transazione Git in base a quattro valori:

• Workspace
• URL del repository
• Hash di commit esatto
• Impronta digitale del modello di sparse checkout (il set esatto di percorsi delle cartelle)

Qualsiasi esecuzione del processo che corrisponde a tutti e quattro i criteri riutilizza una voce della cache, che rimane valida per un massimo di una settimana. Ad esempio, se sono presenti tre processi diversi e tutti hanno gli stessi criteri, usano la stessa cache nel repository fino a quando non è presente un nuovo commit (di dopo 1 settimana).

Ogni modello di checkout sparso univoco crea un'impronta digitale separata e quindi una voce di cache separata. Se 20 utenti aggiungono una cartella personalizzata al modello, il sistema crea 20 chiavi di cache distinte e importa l'albero delle cartelle condivise 20 volte, moltiplicando il carico nell'area di lavoro. La creazione di un unico schema di estrazione diradata che include tutte le 20 cartelle, come ad esempio una cartella principale, consente a una singola cache di funzionare più frequentemente e di ottenere prestazioni migliori nei processi. Il compromesso è un numero maggiore di file nel checkout.

Decidere se usare il checkout di tipo sparse

Abilita il sparse checkout solo se il tuo caso d'uso rispecchia entrambi i seguenti criteri:

• Dimensioni: il repository è di grandi dimensioni (ad esempio, supera 2.500 file).
• Destinazione stabile: il ramo di destinazione viene aggiornato raramente (ad esempio, circa un commit all'ora o meno). Evitare rami che cambiano rapidamente a causa di flussi di lavoro CI/CD automatizzati.

Se si utilizza il checkout sparse, l'organizzazione deve adottare una o entrambe le seguenti strategie di pattern:

• Standardizzazione: usare un massimo di tre modelli di checkout condivisi nell'organizzazione per massimizzare i colpi di cache.
• Micro-targeting: Strutturare i modelli in modo che ciascuno miri a un numero ridotto di file. Per ottenere prestazioni ottimali, impostare come destinazione meno di 200 file.

Questi possono aiutare a ridurre al minimo la velocità di importazione.

Calcolare la velocità di importazione

Prima di abilitare il sparse checkout, stima la velocità di importazione prevista di file all'ora. I limiti si applicano a livello di area di lavoro per tutti i processi e gli utenti.

File all'ora = Processi eseguiti all'ora × tasso di mancato utilizzo della cache × file importati per errore

Esempio: 180 esecuzioni/ora × 10% frequenza di mancata esecuzione × 6.000 file/miss = 108.000 file/ora

Confrontare il risultato con queste soglie:

Procedure consigliate

Standardizzare i modelli

• Operazione: pubblicare tre o meno modelli sparse approvati per ogni repository. I modelli condivisi consolidano il carico e ottimizzano i riscontri nella cache.
• Non: consente modelli personalizzati per ogni team. Anche una cartella aggiuntiva crea una nuova voce della cache e attiva una nuova importazione completa.

Gestire la frequenza del commit

• Operazione: indirizzare i job a un ramo di rilascio stabile. Le merge batch vengono effettuate nelle finestre di rilascio programmate, in modo che più esecuzioni condividano lo stesso commit memorizzato nella cache.
• Non: usare estrazioni sparse con rami aggiornati di frequente, come master o main. Poiché la cache si basa sull'hash di commit esatto, ogni nuovo commit invalida la cache e provoca una nuova importazione completa per ogni esecuzione del processo.

Gestire il carico

• Operazione: rimuovere file binari di grandi dimensioni, artefatti generati e file di dati dal controllo del codice sorgente per ridurre le dimensioni del repository in modo incondizionato.
• Non: lasciare i processi ridondanti in esecuzione ad alta frequenza. Rendere più bassa la frequenza di trigger per i processi che non richiedono un'esecuzione continua, sfasare le pianificazioni, o consolidare i processi che condividono lo stesso checkout.

Gestire il churn dei commit con un branch di rilascio

Quando i processi hanno come destinazione un ramo in rapida spostamento come master o main, l'hash di commit cambia frequentemente, causando mancati riscontri nella cache in quasi ogni esecuzione. L'uso di un ramo di rilascio dedicato che viene aggiornato in base a una pianificazione fissa migliora la frequenza di riscontri nella cache.

Puntando tutti i processi a un ramo di rilascio orario, tutte le esecuzioni entro tale ora vengono risolte nello stesso hash di commit e condividono la stessa voce della cache.

Per configurare un branch di rilascio:

1. Creare un ramo di lunga durata, ad esempio release-candidate, nel repository Git.
2. Automatizzare l'aggiornamento di questo ramo in modo che corrisponda a master secondo una pianificazione fissa, ad esempio all'inizio di ogni ora.
3. Configura i tuoi processi basati su Git per utilizzare release-candidate come riferimento Git di destinazione.

Esaminare questi compromessi prima di implementare:

Esempio: automatizzare con GitHub Actions

Il flusso di lavoro GitHub Actions seguente consente di automatizzare un taglio orario del ramo di rilascio.

Passaggio 1: Eseguire il commit di un .github/workflows/cut-release-branch.yml file nel repository:

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

Passaggio 2: attivare manualmente l'azione di GitHub per verificare che il ramo release-candidate sia stato creato.

Passaggio 3: Aggiornare i processi esistenti per utilizzare release-candidate come riferimento Git di destinazione.

Abilitare lo sparse checkout usando l'API dei Job

Per abilitare il checkout di tipo sparse, includere sparse_checkout all'interno di git_source durante la creazione o l'aggiornamento di un processo:

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

Ogni stringa in patterns è un percorso di directory relativo alla radice del repository. Tutti i file all'interno di ogni directory specificata sono inclusi nel checkout.