Plugin Jobs

Lanza y supervisa Databricks Lakeflow Jobs desde tu aplicación AppKit.

Características principales:

• Compatibilidad con varios jobs mediante claves de job con nombre
• Descubrimiento automático de jobs a partir de variables de entorno
• Ejecución con espera y actualizaciones de estado en streaming mediante SSE
• Validación de parámetros con esquemas de Zod
• Mapeo de parámetros según el tipo de tarea (notebook, python_wheel, sql, etc.)

Uso básico

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

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

Si no hay una configuración explícita de jobs, el plugin lee DATABRICKS_JOB_ID del entorno y lo registra bajo la clave default.

Opciones de configuración

Configuración por job (JobConfig)

Variables de entorno

Modo de job único

Define DATABRICKS_JOB_ID para exponer un job bajo la clave default:

DATABRICKS_JOB_ID=123456

const handle = AppKit.jobs("default");

Modo multi-job

Define DATABRICKS_JOB_<NAME> para cada job:

DATABRICKS_JOB_ETL=123456
DATABRICKS_JOB_ML=789012

const etl = AppKit.jobs("etl");
const ml  = AppKit.jobs("ml");

Los nombres de las variables de entorno se escriben en mayúsculas; las claves de job, en minúsculas. Los jobs detectados a partir del entorno se combinan con cualquier configuración explícita de jobs: la configuración explícita tiene prioridad.

Validación de parámetros

Usa params para aplicar un esquema de Zod en tiempo de ejecución. Los parámetros no válidos se rechazan con un 400 antes de ejecutar el job:

import { z } from "zod";

jobs({
  jobs: {
    etl: {
      params: z.object({
        startDate: z.string(),
        endDate: z.string(),
        dryRun: z.boolean().optional(),
      }),
    },
  },
})

Correspondencia de tipos de tarea

Cuando se define taskType, el plugin asigna automáticamente los parámetros validados a los campos de solicitud correctos del SDK:

jobs({
  jobs: {
    etl: {
      taskType: "notebook",
      params: z.object({
        startDate: z.string(),
        endDate: z.string(),
      }),
    },
  },
})

Cuando se omite taskType, los parámetros se pasan al SDK tal cual.

Contexto de ejecución

Los jobs siempre se ejecutan como el service principal de la app. El resource binding de la app (databricks.yml) otorga CAN_MANAGE_RUN al SP, de modo que los usuarios pueden iniciar runs sin necesidad de grants individuales. La atribución de cada run en la UI de Jobs muestra el SP de la app, no al usuario humano.

Endpoints HTTP

Todas las rutas se montan bajo /api/jobs.

Lanzar un run

Devuelve { "runId": 12345 }.

Agrega ?stream=true para recibir actualizaciones de estado mediante SSE, que se consultan periódicamente hasta que el run finaliza:

Cada evento SSE contiene { status, timestamp, run }.

Listar runs

Devuelve { "runs": [...] }. El límite se restringe al rango 1–100; el valor predeterminado es 20.

Obtener los detalles del run

Obtener el estado más reciente

Devuelve { "status": "TERMINATED", "run": { ... } } para el run más reciente.

Cancelar un run

Devuelve 204 No Content si la operación se realiza correctamente.

Acceso programático

El plugin exporta una función invocable que selecciona un job por clave:

const AppKit = await createApp({
  plugins: [
    server(),
    jobs({
      jobs: {
        etl: { taskType: "notebook" },
      },
    }),
  ],
});

const etl = AppKit.jobs("etl");

// Lanzar un run
const result = await etl.runNow({ startDate: "2025-01-01" });
if (result.ok) {
  console.log("Run ID:", result.data.run_id);
}

// Lanzar y sondear hasta que finalice
for await (const status of etl.runAndWait({ startDate: "2025-01-01" })) {
  console.log(status.status); // "PENDING", "RUNNING", "TERMINATED", etc.
}

// Operaciones de lectura
await etl.lastRun();
await etl.listRuns({ limit: 10 });
await etl.getRun(12345);
await etl.getRunOutput(12345);
await etl.getJob();

// Cancelar
await etl.cancelRun(12345);

Todos los métodos devuelven ExecutionResult<T>: comprueba result.ok antes de acceder a result.data.

Valores predeterminados de ejecución