Plugin Jobs

Dispare e monitore Databricks Lakeflow Jobs a partir do seu app AppKit.

Principais recursos:

• Suporte a múltiplos jobs com chaves de job nomeadas
• Descoberta automática de jobs a partir de variáveis de ambiente
• Execução com espera e atualizações de status via streaming SSE
• Validação de parâmetros com schemas Zod
• Mapeamento de parâmetros conforme o tipo de tarefa (notebook, python_wheel, sql, etc.)

Uso básico

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

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

Sem uma configuração jobs explícita, o plugin lê DATABRICKS_JOB_ID do ambiente e o registra sob a chave default.

Opções de configuração

Configuração por job (JobConfig)

Variáveis de ambiente

Modo de job único

Defina DATABRICKS_JOB_ID para expor um job na chave default:

DATABRICKS_JOB_ID=123456

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

Modo multi-job

Defina DATABRICKS_JOB_<NAME> para cada job:

DATABRICKS_JOB_ETL=123456
DATABRICKS_JOB_ML=789012

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

Os nomes das variáveis de ambiente ficam em maiúsculas; as chaves de job, em minúsculas. Os jobs descobertos no ambiente são mesclados com qualquer configuração explícita de jobs — a configuração explícita prevalece.

Validação de parâmetros

Use params para aplicar um schema Zod em runtime. Parâmetros inválidos são rejeitados com um 400 antes de o job ser acionado:

import { z } from "zod";

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

Mapeamento de tipos de tarefa

Quando taskType está definido, o plugin mapeia automaticamente os parâmetros validados para os campos de requisição corretos do SDK:

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

Quando taskType é omitido, os parâmetros são repassados ao SDK sem alterações.

Contexto de execução

Os jobs sempre são executados como o service principal do app. A vinculação de recurso do app (databricks.yml) concede CAN_MANAGE_RUN ao SP, de modo que os usuários disparam runs sem precisar de grants individuais. A atribuição de cada run na UI de Jobs mostra o SP do app, e não o usuário humano.

Endpoints HTTP

Todas as rotas são montadas sob /api/jobs.

Acionar um run

Retorna { "runId": 12345 }.

Adicione ?stream=true para receber atualizações de status via SSE, que fazem polling até a conclusão do run:

Cada evento SSE contém { status, timestamp, run }.

Listar runs

Retorna { "runs": [...] }. O limite é ajustado ao intervalo de 1 a 100, com padrão de 20.

Obter detalhes do run

Obter o status mais recente

Retorna { "status": "TERMINATED", "run": { ... } } para o run mais recente.

Cancelar um run

Retorna 204 No Content em caso de sucesso.

Acesso programático

O plugin exporta um callable que seleciona um job por chave:

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

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

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

// Dispara e monitora até a conclusão
for await (const status of etl.runAndWait({ startDate: "2025-01-01" })) {
  console.log(status.status); // "PENDING", "RUNNING", "TERMINATED", etc.
}

// Operações de leitura
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 os métodos retornam ExecutionResult<T> — verifique result.ok antes de acessar result.data.

Padrões de execução