Lakeflow Jobs

Pour déporter un traitement trop lent ou trop lourd pour un gestionnaire de requêtes, vous avez besoin d'un Lakeflow Job, le moteur d'exécution géré de Databricks pour les tâches notebook, SQL, dbt et wheel Python. Exemples typiques de traitements déclenchés par une action utilisateur : réentraînement de modèle, ETL multitâche ou backfill SQL de longue durée. Le plugin Jobs relie votre gestionnaire à un job : déclarez-le dans databricks.yml, puis appelez AppKit.jobs("default").runNow(params) pour déclencher une exécution, ou itérez sur runAndWait pour suivre la progression en streaming.

La création des jobs se fait côté workspace, dans Databricks ou avec les Declarative Automation Bundles. Depuis une app AppKit, vous vous contentez de les déclencher. Le plugin prend en charge l'interrogation périodique des exécutions, le streaming SSE (Server-Sent Events) et la validation des paramètres avec Zod.

Prérequis

• Databricks CLI v1.0.0+ avec un profil authentifié.
• Une application AppKit en cours d'exécution. Consultez le Démarrage rapide des apps.
• Un Lakeflow Job défini dans votre workspace. Consultez Create your first job pour la procédure de configuration.

Brancher le plugin Jobs

Enregistrez le plugin dans createApp. Il expose AppKit.jobs(...) à vos gestionnaires et lit les identifiants de jobs à partir des variables d'environnement que vous déclarez dans app.yaml.

import { createApp, jobs, server } from "@databricks/appkit";

await createApp({
  plugins: [server(), jobs()],
});

En l'absence de configuration jobs explicite, le plugin lit DATABRICKS_JOB_ID depuis l'environnement et l'enregistre sous la clé default. La déclaration de plusieurs jobs nommés n'est pas encore prise en charge au moment du déploiement : associez donc un seul job à DATABRICKS_JOB_ID.

Lier le job

Déclarez le job comme ressource dans databricks.yml. Lors du déploiement, la plateforme Apps accorde automatiquement l'autorisation CAN_MANAGE_RUN à votre service principal :

resources:
  apps:
    my-app:
      resources:
        - name: etl-job
          job:
            id: ${var.etl_job_id}
            permission: CAN_MANAGE_RUN

Injectez l'ID du job dans app.yaml sous le nom DATABRICKS_JOB_ID, la variable d'environnement que lit le job par défaut du plugin :

env:
  - name: DATABRICKS_JOB_ID
    valueFrom: etl-job

Consultez Configuration de l'application pour la liste complète des ressources et la référence du plugin Jobs pour les règles de nommage des variables d'environnement.

Déclencher depuis un gestionnaire de route

Utilisez runNow pour un déclenchement ponctuel. Encapsulez les paramètres dans un schéma Zod : le plugin rejette alors les entrées invalides avec un 400, avant même l'appel au SDK.

import { createApp, jobs, server } from "@databricks/appkit";
import { z } from "zod";

const AppKit = await createApp({
  plugins: [
    server(),
    jobs({
      jobs: {
        default: {
          taskType: "notebook",
          params: z.object({
            startDate: z.string(),
            endDate: z.string(),
          }),
        },
      },
    }),
  ],
});

AppKit.server.extend((app) => {
  app.post("/api/etl/run", async (req, res) => {
    const result = await AppKit.jobs("default").runNow({
      startDate: req.body.startDate,
      endDate: req.body.endDate,
    });
    if (!result.ok) return res.status(500).json({ error: result.error });
    res.json({ runId: result.data.run_id });
  });
});

Toutes les méthodes du plugin Jobs renvoient ExecutionResult<T>. Vérifiez result.ok avant de lire result.data.

Les jobs s'exécutent sous l'identité du service principal de l'application. Le resource binding lui accorde CAN_MANAGE_RUN : les utilisateurs peuvent ainsi déclencher des exécutions sans grants individuels, et l'interface Jobs attribue chaque exécution au service principal plutôt qu'à l'utilisateur humain. AppKit n'exécute pas de jobs pour le compte de l'utilisateur connecté : il n'y a donc aucune exécution de job par utilisateur à configurer.

Diffuser la progression en direct

Le plugin expose un endpoint SSE intégré sur POST /api/jobs/:jobKey/run?stream=true. Chaque événement transmet { status, timestamp, run } jusqu'à la fin de l'exécution.

Côté serveur, itérez directement sur runAndWait. Il s'agit d'un itérateur asynchrone, et non d'une promesse :

for await (const status of AppKit.jobs("default").runAndWait({
  startDate,
  endDate,
})) {
  // status.status passe successivement par PENDING, RUNNING, TERMINATED, etc.
}

L'API complète du hook et les utilitaires de pagination sont décrits dans la référence du plugin Jobs.

Autorisations

Définissez permission: CAN_MANAGE_RUN sur le resource binding du job. C'est le privilège minimal requis pour une application qui se contente de déclencher des jobs existants et de lire leur état.

Polling, webhooks ou tables système

Choisissez le modèle adapté à la durée d'exécution et à votre interface :

• L'endpoint intégré du plugin qui lance l'exécution et attend son issue convient lorsque l'utilisateur accepte de patienter sur la page. Le navigateur maintient une connexion SSE pendant que le plugin interroge le SDK toutes les quelques secondes (5 s par défaut, avec un délai d'expiration de 10 minutes).
• Les notifications par webhook conviennent lorsque l'utilisateur ferme l'onglet et que le résultat ne vous est utile que plus tard. Configurez les destinations webhook_notifications.on_success / on_failure, écrivez l'état de l'exécution dans un stockage durable (Lakebase est pratique si votre application l'utilise déjà), puis diffusez les mises à jour vers le client au rechargement de la page.
• system.lakeflow.job_run_timeline est interrogeable via l'Analytics plugin dès lors que votre service principal dispose du privilège SELECT sur cette table. Utile pour les tableaux de bord d'historique d'exécutions ou les analyses inter-jobs.

Et ensuite

Consultez Pipelines and freshness pour le volet lecture : l'affichage des horodatages « dernière mise à jour » à côté des données alimentées par un job. Vous pouvez aussi parcourir le catalogue de modèles pour découvrir d'autres points de départ.