Uso de Git con trabajos de Lakeflow

Las tareas de trabajo pueden consultar el código fuente directamente desde un repositorio de Git remoto.

Los siguientes tipos de tareas admiten repositorios de Git remotos:

• Blocs de notas
• scripts de Python
• Archivos SQL
• proyectos de herramienta de construcción de datos (dbt)

Todas las tareas de un trabajo deben hacer referencia a la misma confirmación en el repositorio remoto. Cuando se inicia una ejecución de trabajo, Azure Databricks toma una instantánea de la rama o commit especificados, para que todas las tareas que se ejecuten en esa ejecución usen la misma versión del código.

Al ver el historial de ejecución de una tarea que ejecuta código almacenado en un repositorio de Git remoto, el panel Detalles de ejecución de tareas incluye detalles de Git, incluido el SHA de confirmación asociado a la ejecución. Para obtener más información, consulte Visualización del historial de ejecución de tareas.

Uso de un origen de repositorio de Git frente al uso de carpetas de Git.

En esta página se describen las tareas que pueden extraer código fuente directamente desde un repositorio de Git remoto. Las áreas de trabajo también admiten una característica denominada carpetas de Git, donde una carpeta del área de trabajo se sincroniza con un repositorio de Git. Una tarea puede usar una carpeta de Git como origen. Sin embargo, debe administrar la sincronización con el repositorio. El uso de un repositorio Git remoto, como se describe aquí, extrae automáticamente el nuevo origen, si está disponible, durante la ejecución del trabajo.

Azure Databricks recomienda hacer referencia a las rutas de acceso del área de trabajo en carpetas de Git solo para la iteración rápida y las pruebas durante el desarrollo. En el caso de los trabajos de ensayo y producción, configure tareas para hacer referencia a un repositorio de Git remoto en su lugar.

Configuración de un proveedor de Git para un trabajo

La interfaz de usuario de trabajos tiene un cuadro de diálogo para configurar un repositorio de Git remoto. Este cuadro de diálogo es accesible desde el panel Detalles del trabajo en el encabezado Git o en cualquier tarea configurada para usar un proveedor de Git. Para acceder al cuadro de diálogo, haga clic en Agregar configuración de Git en el panel Detalles del trabajo .

En el cuadro de diálogo Git (con la etiqueta Información de Git si se tiene acceso durante la configuración de la tarea), escriba los siguientes detalles:

• La dirección URL del repositorio de Git.
• Seleccione el proveedor de Git en la lista desplegable.
• En el campo de referencia de Git, escriba el identificador de una rama, etiqueta o confirmación que corresponda a la versión del código fuente que desea ejecutar.
• Seleccione rama, etiqueta o confirmación en la lista desplegable.

Debe especificar solo una de las siguientes opciones:

• branch: el nombre de la rama, por ejemplo, main.
• tag: el nombre de la etiqueta, por ejemplo, release-1.0.0.
• commit: hash de una confirmación específica, por ejemplo, e0056d01.

Al ver el historial de ejecución de una tarea que ejecuta un código almacenado en un repositorio Git remoto, el panel Detalles de ejecución de tareas incluye detalles de Git, incluido el SHA de confirmación asociado a la ejecución. Para obtener más información, consulte Visualización del historial de ejecución de tareas.

Extracción parcial para repositorios grandes

Para los repositorios de gran tamaño, puede utilizar el checkout disperso para importar solo directorios específicos en lugar del repositorio completo. La comprobación dispersa reduce el tiempo de checkout y el uso de recursos en cada ejecución de tarea.

Sin embargo, la configuración incorrecta puede provocar la fragmentación de la memoria caché, lo que degrada los tiempos de ejecución en todo el área de trabajo. En esta sección se describen las compensaciones y los problemas que pueden surgir al usar la extracción parcial.

Cómo Azure Databricks almacena en caché las extracciones del repositorio

Azure Databricks almacena en caché cada extracción de Git en función de cuatro valores:

• Workspace
• Dirección URL del repositorio
• Hash de confirmación exacto
• Huella digital del patrón de comprobación dispersa (el conjunto exacto de rutas de acceso de carpeta)

Cualquier ejecución de trabajo que coincida con los cuatro criterios reutiliza una entrada de caché, que sigue siendo válida durante hasta una semana. Por ejemplo, si tiene tres trabajos diferentes y todos tienen los mismos criterios, usan la misma caché en el repositorio hasta que haya una nueva confirmación (de después de 1 semana).

Cada patrón de extracción dispersa único crea un identificador independiente y, por tanto, una entrada de caché independiente. Si cada 20 usuarios agregan una carpeta personalizada a su patrón, el sistema crea 20 claves de caché distintas e importa el árbol de carpetas compartidas 20 veces, multiplicando la carga en el área de trabajo. Crear un único patrón de checkout disperso que incluya las 20 carpetas (por ejemplo, si se trata de una carpeta madre), permite que una sola caché funcione con más frecuencia y tenga un mejor rendimiento en los trabajos. La compensación es un mayor número de archivos en la compra.

Decidir si usar la extracción dispersa

Solo active la extracción dispersa si el caso de uso cumple los dos criterios siguientes:

• Tamaño: el repositorio es grande (por ejemplo, supera los 2500 archivos).
• Destino estable: la rama de destino se actualiza con poca frecuencia (por ejemplo, aproximadamente una confirmación por hora o menos). Evite las ramas que cambian rápidamente debido a flujos de trabajo automatizados de CI/CD.

Si usa un checkout disperso, la organización también debe adoptar una o ambas de las siguientes estrategias de patrones:

• Normalización: Utilice tres o menos patrones de checkout compartidos en toda la organización para maximizar los aciertos de caché.
• Micro-targeting: patrones de estructura para que cada uno tenga como destino un pequeño número de archivos. Para obtener el mejor rendimiento, apunte a menos de 200 archivos.

Esto puede ayudar a minimizar la tasa de importación.

Cálculo de la tasa de importación

Antes de habilitar el checkout disperso, calcule la tasa de importación de archivos por hora proyectada. Los límites se aplican en el nivel de área de trabajo en todos los trabajos y usuarios.

Archivos por hora = ejecuciones de trabajos por hora × tasa de errores de caché × archivos importados por error

Ejemplo: 180 ejecuciones/hora × 10% tasa de fallos × 6 000 archivos/fallo = 108 000 archivos/hora

Compare el resultado con estos umbrales:

Procedimientos recomendados

Estandarizar patrones

• Do: Publique tres o menos patrones dispersos aprobados por repositorio. Los patrones compartidos consolidan la carga y maximizan los aciertos de caché.
• No: permitir patrones personalizados por equipo. Incluso una carpeta adicional crea una nueva entrada de caché y desencadena una nueva importación completa.

Gestión del cambio frecuente de commits

• Do: Apunte los trabajos en una rama de versión estable. Batch se integra en ventanas de lanzamiento programadas para que varias ejecuciones compartan el mismo commit en caché.
• No: utilices checkouts dispersos con ramas que se actualizan con frecuencia, como master o main. Dado que la memoria caché se basa en el hash de confirmación exacto, cada nueva confirmación invalida la memoria caché y provoca una nueva importación completa para cada ejecución de trabajo.

Administración de la carga

• Do: Quite archivos binarios grandes, artefactos generados y archivos de datos del control de código fuente para reducir el tamaño del repositorio incondicionalmente.
• No: deje que los trabajos redundantes se ejecuten con alta frecuencia. Menor frecuencia de activación para los trabajos que no requieren ejecución continua, escalonar horarios o consolidar trabajos que comparten la misma extracción.

Gestión de la volatilidad de confirmaciones con una rama de lanzamiento

Cuando los trabajos tienen como destino una rama de movimiento rápido como master o main, el hash de confirmación cambia con frecuencia, lo que provoca errores de caché en casi todas las ejecucións. El uso de una rama de versión dedicada que se actualiza según una programación fija mejora las tasas de aciertos de caché.

Al apuntar todos los trabajos a una rama de lanzamientos horarios, todas las ejecuciones dentro de esa hora apuntan al mismo hash de confirmación y comparten la misma entrada de caché.

Para configurar una rama de versión:

1. Cree una rama de larga duración (por ejemplo, release-candidate) en el repositorio de Git.
2. Automatice la actualización de esta rama para que coincida con master en una programación fija, como al comienzo de cada hora.
3. Configure los trabajos respaldados por Git para usar release-candidate como su referencia de Git de destino.

Revise estos inconvenientes antes de implementar:

Ejemplo: automatización con GitHub Actions

El siguiente flujo de trabajo de GitHub Actions automatiza un corte de rama de versión por hora.

Paso 1: Confirmar un .github/workflows/cut-release-branch.yml archivo en el repositorio:

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: desencadene manualmente la acción de GitHub para comprobar que se crea la rama release-candidate.

Paso 3: Actualice los trabajos existentes para usarlos release-candidate como referencia de Git de destino.

Habilitar el checkout disperso utilizando la API de Jobs

Para habilitar el checkout disperso, incluya un sparse_checkout bloque dentro de git_source al crear o actualizar un trabajo.

{
  "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 cadena de patterns es una ruta de acceso de directorio relativa a la raíz del repositorio. Todos los archivos de cada directorio especificado se incluyen en la extracción.