Referência de tabela do sistema Jobs

Este artigo é uma referência para as tabelas do sistema lakeflow, que registram a atividade de trabalho em sua conta. Essas tabelas incluem registros de todos os espaços de trabalho na sua conta implantados na mesma região de nuvem. Para ver registros de outra região, você deve exibir as tabelas de um workspace implantado nessa região.

Requirements

• Para acessar essas tabelas do sistema, os usuários devem:
  • Ser um administrador do metastore e um administrador de conta ou
  • Tenha permissões de USE e SELECT nos esquemas do sistema. Veja Conceder acesso às tabelas do sistema.

Tabelas de trabalhos disponíveis

Todas as tabelas de sistema relacionadas ao trabalho residem no system.lakeflow esquema. Atualmente, o esquema hospeda quatro tabelas:

Referência de esquema detalhada

As seções a seguir fornecem referências de esquema para cada uma das tabelas do sistema relacionadas a trabalhos.

Esquema da tabela de trabalhos

A tabela jobs é uma SCD2 (tabela de dimensões de alteração lenta). Quando uma linha é alterada, uma nova linha é emitida, substituindo logicamente a anterior.

Caminho da tabela: system.lakeflow.jobs

Consulta de exemplo

-- Get the most recent version of a job
SELECT
  *,
  ROW_NUMBER() OVER(PARTITION BY workspace_id, job_id ORDER BY change_time DESC) as rn
FROM
  system.lakeflow.jobs QUALIFY rn=1

Esquema da tabela da tarefa de trabalho

A tabela de tarefas de trabalho é uma SCD2 (tabela de dimensões de alteração lenta). Quando uma linha é alterada, uma nova linha é emitida, substituindo logicamente a anterior.

Caminho da tabela: system.lakeflow.job_tasks

Consulta de exemplo

-- Get the most recent version of a job task
SELECT
  *,
  ROW_NUMBER() OVER(PARTITION BY workspace_id, job_id ORDER BY change_time DESC) as rn
FROM
  system.lakeflow.job_tasks QUALIFY rn=1

Esquema da tabela da linha do tempo de execução do trabalho

A tabela de linha do tempo de execução do trabalho é imutável e completa no momento em que é produzida.

Caminho da tabela: system.lakeflow.job_run_timeline

Consulta de exemplo

-- This query gets the daily job count for a workspace for the last 7 days:
SELECT
  workspace_id,
  COUNT(DISTINCT run_id) as job_count,
  to_date(period_start_time) as date
FROM system.lakeflow.job_run_timeline
WHERE
  period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
GROUP BY ALL

-- This query returns the daily job count for a workspace for the last 7 days, distributed by the outcome of the job run.
SELECT
  workspace_id,
  COUNT(DISTINCT run_id) as job_count,
  result_state,
  to_date(period_start_time) as date
FROM system.lakeflow.job_run_timeline
WHERE
  period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
  AND result_state IS NOT NULL
GROUP BY ALL

-- This query returns the average time of job runs, measured in seconds. The records are organized by job. A top 90 and a 95 percentile column show the average lengths of the job's longest runs.
with job_run_duration as (
    SELECT
        workspace_id,
        job_id,
        run_id,
        CAST(SUM(period_end_time - period_start_time) AS LONG) as duration
    FROM
        system.lakeflow.job_run_timeline
    WHERE
      period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
    GROUP BY ALL
)
SELECT
    t1.workspace_id,
    t1.job_id,
    COUNT(DISTINCT t1.run_id) as runs,
    MEAN(t1.duration) as mean_seconds,
    AVG(t1.duration) as avg_seconds,
    PERCENTILE(t1.duration, 0.9) as p90_seconds,
    PERCENTILE(t1.duration, 0.95) as p95_seconds
FROM
    job_run_duration t1
GROUP BY ALL
ORDER BY mean_seconds DESC
LIMIT 100

-- This query provides a historical runtime for a specific job based on the `run_name` parameter. For the query to work, you must set the `run_name`.
SELECT
  workspace_id,
  run_id,
  SUM(period_end_time - period_start_time) as run_time
FROM system.lakeflow.job_run_timeline
WHERE
  run_type="SUBMIT_RUN"
  AND run_name = :run_name
  AND period_start_time > CURRENT_TIMESTAMP() - INTERVAL 60 DAYS
GROUP BY ALL

-- This query collects a list of retried job runs with the number of retries for each run.
with repaired_runs as (
    SELECT
    workspace_id, job_id, run_id, COUNT(*) - 1 as retries_count
    FROM system.lakeflow.job_run_timeline
    WHERE result_state IS NOT NULL
    GROUP BY ALL
    HAVING retries_count > 0
    )
SELECT
    *
FROM repaired_runs
ORDER BY retries_count DESC
    LIMIT 10;

Esquema da tabela da linha do tempo de execução da tarefa de trabalho

A tabela de linha do tempo de execução de tarefa de trabalho é imutável e concluída no momento em que é produzida.

Caminho da tabela: system.lakeflow.job_task_run_timeline

Esquema de tabela de pipelines

A tabela de pipelines é uma SCD2 (tabela de dimensões de alteração lenta). Quando uma linha é alterada, uma nova linha é emitida, substituindo logicamente a anterior.

Caminho da tabela: system.lakeflow.pipelines

Consulta de exemplo

-- Get the most recent version of a pipeline
SELECT
  *,
  ROW_NUMBER() OVER(PARTITION BY workspace_id, pipeline_id ORDER BY change_time DESC) as rn
FROM
  system.lakeflow.pipelines QUALIFY rn=1

-- Enrich billing logs with pipeline metadata
with latest_pipelines AS (
  SELECT
    *,
    ROW_NUMBER() OVER(PARTITION BY workspace_id, pipeline_id ORDER BY change_time DESC) as rn
  FROM
    system.lakeflow.pipelines QUALIFY rn=1
)
SELECT
  usage.*,
  pipelines.*
FROM system.billing.usage
LEFT JOIN latest_pipelines
  ON (usage.workspace_id = pipelines.workspace_id
    AND usage.usage_metadata.dlt_pipeline_id = pipelines.pipeline_id)
WHERE
  usage.usage_metadata.dlt_pipeline_id IS NOT NULL

Esquema da tabela de cronograma de atualização do pipeline

A tabela da linha do tempo de atualização do pipeline é imutável e completa no momento em que é produzida.

Caminho da tabela: system.lakeflow.pipeline_update_timeline

Consulta de exemplo

-- This query gets the daily pipeline update count for a workspace for the last 7 days:
SELECT
    workspace_id,
    COUNT(DISTINCT update_id) as update_count,
    to_date(period_start_time) as date
FROM system.lakeflow.pipeline_update_timeline
WHERE
    period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
GROUP BY ALL

-- This query returns the daily pipeline update count for a workspace for the last 7 days, distributed by the outcome of the pipeline update.
SELECT
    workspace_id,
    COUNT(DISTINCT update_id) as update_count,
    result_state,
    to_date(period_start_time) as date
FROM system.lakeflow.pipeline_update_timeline
WHERE
    period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
  AND result_state IS NOT NULL
GROUP BY ALL

-- This query returns the average time of pipeline updates, measured in seconds. The records are organized by pipeline. A top 90 and a 95 percentile column show the average lengths of the pipeline's longest updates.
with pipeline_update_duration as (
    SELECT
      workspace_id,
      pipeline_id,
      update_id,
      CAST(SUM(period_end_time - period_start_time) AS LONG) as duration
    FROM
        system.lakeflow.pipeline_update_timeline
    WHERE
        period_start_time > CURRENT_TIMESTAMP() - INTERVAL 7 DAYS
    GROUP BY ALL
)
SELECT
    t1.workspace_id,
    t1.pipeline_id,
    COUNT(DISTINCT t1.update_id) as update_count,
    MEAN(t1.duration) as mean_seconds,
    AVG(t1.duration) as avg_seconds,
    PERCENTILE(t1.duration, 0.9) as p90_seconds,
    PERCENTILE(t1.duration, 0.95) as p95_seconds
FROM
    pipeline_update_duration t1
GROUP BY ALL
ORDER BY mean_seconds DESC
    LIMIT 100

Padrões de junção comuns

As seções a seguir fornecem consultas de exemplo que realçam padrões de junção comumente usados para tabelas do sistema de trabalhos.

Unir as tabelas de trabalhos e linha do tempo de execução de trabalhos

aprimorar a execução do trabalho com um nome de trabalho

with jobs as (
    SELECT
        *,
        ROW_NUMBER() OVER (PARTITION BY workspace_id, job_id ORDER BY change_time DESC) as rn
    FROM system.lakeflow.jobs QUALIFY rn=1
)
SELECT
    job_run_timeline.*
    jobs.name
FROM system.lakeflow.job_run_timeline
    LEFT JOIN jobs USING (workspace_id, job_id)

Unir as tabelas de linha do tempo de execução de trabalhos e uso

Enriquecer cada log de faturamento com metadados de execução de tarefas

A consulta a seguir enriquece os logs de cobrança com metadados de execução de jobs do tipo clássico e sem servidor.

with aggregated_job_runs AS (
  SELECT
    j.workspace_id,
    COALESCE(t.job_id, j.job_id) as origin_job_id,
    COALESCE(t.job_run_id, j.run_id) AS origin_job_run_id,
    j.job_id as billing_job_id,
    j.run_id as billing_run_id,
    CASE WHEN j.root_task_run_id IS NOT NULL THEN true ELSE false END AS is_workflow_run
  FROM
    system.lakeflow.job_run_timeline j
  LEFT JOIN
    system.lakeflow.job_task_run_timeline t
  ON
    j.workspace_id = t.workspace_id
    AND j.root_task_run_id = t.run_id
  WHERE j.period_start_time >= CURRENT_DATE() - INTERVAL 7 DAYS
  GROUP BY ALL
),
billing_logs_enriched AS (
  SELECT
      t2.origin_job_id,
      t2.origin_job_run_id,
      t1.*
  FROM system.billing.usage t1
      INNER JOIN aggregated_job_runs t2
          ON t1.workspace_id = t2.workspace_id
              AND t1.usage_metadata.job_id = t2.billing_job_id
              AND t1.usage_metadata.job_run_id = t2.billing_run_id
  WHERE
      billing_origin_product="JOBS" AND usage_date >= CURRENT_DATE() - INTERVAL 7 DAYS
)
SELECT
  workspace_id,
  origin_job_id AS job_id,
  origin_job_run_id AS run_id,
  sku_name,
  SUM(usage_quantity) as total_usage_quantity,
  SUM(CASE WHEN usage_metadata.job_run_id != origin_job_run_id THEN usage_quantity ELSE 0 END) AS workflow_run_usage_quantity,
  COUNT(DISTINCT usage_metadata.job_run_id) - 1 AS workflow_runs
FROM billing_logs_enriched
GROUP BY ALL

Calcular custo por execução de trabalho

Essa consulta une-se à tabela do sistema billing.usage para calcular um custo por execução de trabalho.

with jobs_usage AS (
  SELECT
    *,
    usage_metadata.job_id,
    usage_metadata.job_run_id as run_id,
    identity_metadata.run_as as run_as
  FROM system.billing.usage
  WHERE billing_origin_product="JOBS"
),
jobs_usage_with_usd AS (
  SELECT
    jobs_usage.*,
    usage_quantity * pricing.default as usage_usd
  FROM jobs_usage
    LEFT JOIN system.billing.list_prices pricing ON
      jobs_usage.sku_name = pricing.sku_name
      AND pricing.price_start_time <= jobs_usage.usage_start_time
      AND (pricing.price_end_time >= jobs_usage.usage_start_time OR pricing.price_end_time IS NULL)
      AND pricing.currency_code="USD"
),
jobs_usage_aggregated AS (
  SELECT
    workspace_id,
    job_id,
    run_id,
    FIRST(run_as, TRUE) as run_as,
    sku_name,
    SUM(usage_usd) as usage_usd,
    SUM(usage_quantity) as usage_quantity
  FROM jobs_usage_with_usd
  GROUP BY ALL
)
SELECT
  t1.*,
  MIN(period_start_time) as run_start_time,
  MAX(period_end_time) as run_end_time,
  FIRST(result_state, TRUE) as result_state
FROM jobs_usage_aggregated t1
  LEFT JOIN system.lakeflow.job_run_timeline t2 USING (workspace_id, job_id, run_id)
GROUP BY ALL
ORDER BY usage_usd DESC
LIMIT 100

Obter os logs de uso para trabalhos SUBMIT_RUN

SELECT
  *
FROM system.billing.usage
WHERE
  EXISTS (
      SELECT 1
      FROM system.lakeflow.job_run_timeline
      WHERE
        job_run_timeline.job_id = usage_metadata.job_id
        AND run_name = :run_name
        AND workspace_id = :workspace_id
  )

Unir as tabelas de linha do tempo de execução de tarefas de trabalho e clusters

Enriquecer a execução das tarefas de trabalho com metadados de clusters

with clusters as (
    SELECT
        *,
        ROW_NUMBER() OVER (PARTITION BY workspace_id, cluster_id ORDER BY change_time DESC) as rn
    FROM system.compute.clusters QUALIFY rn=1
),
exploded_task_runs AS (
  SELECT
    *,
    EXPLODE(compute_ids) as cluster_id
  FROM system.lakeflow.job_task_run_timeline
  WHERE array_size(compute_ids) > 0
)
SELECT
  *
FROM exploded_task_runs t1
  LEFT JOIN clusters t2
    USING (workspace_id, cluster_id)

Encontre trabalhos em execução na computação de uso geral

Essa consulta une-se à tabela do sistema compute.clusters para retornar trabalhos recentes que estão em execução na computação para todas as finalidades em vez da computação de trabalhos.

with clusters AS (
  SELECT
    *,
    ROW_NUMBER() OVER(PARTITION BY workspace_id, cluster_id ORDER BY change_time DESC) as rn
  FROM system.compute.clusters
  WHERE cluster_source="UI" OR cluster_source="API"
  QUALIFY rn=1
),
job_tasks_exploded AS (
  SELECT
    workspace_id,
    job_id,
    EXPLODE(compute_ids) as cluster_id
  FROM system.lakeflow.job_task_run_timeline
  WHERE period_start_time >= CURRENT_DATE() - INTERVAL 30 DAY
  GROUP BY ALL
),
all_purpose_cluster_jobs AS (
  SELECT
    t1.*,
    t2.cluster_name,
    t2.owned_by,
    t2.dbr_version
  FROM job_tasks_exploded t1
    INNER JOIN clusters t2 USING (workspace_id, cluster_id)
)
SELECT * FROM all_purpose_cluster_jobs LIMIT 10;

Localizar trabalhos que não foram executados nos últimos 30 dias

Essa consulta une as tabelas do sistema lakeflow.jobs e lakeflow.job_run_timeline para retornar trabalhos que não foram executados nos últimos 30 dias.

with latest_jobs AS (
    SELECT
        *,
        ROW_NUMBER() OVER (PARTITION BY workspace_id, job_id ORDER BY change_time DESC) as rn
    FROM system.lakeflow.jobs QUALIFY rn=1
),
latest_not_deleted_jobs AS (
    SELECT
        workspace_id,
        job_id,
        name,
        change_time,
        tags
    FROM latest_jobs WHERE delete_time IS NULL
),
last_seen_job_timestamp AS (
    SELECT
        workspace_id,
        job_id,
        MAX(period_start_time) as last_executed_at
    FROM system.lakeflow.job_run_timeline
    WHERE
        run_type="JOB_RUN"
    GROUP BY ALL
)
SELECT
    t1.workspace_id,
    t1.job_id,
    t1.name,
    t1.change_time as last_modified_at,
    t2.last_executed_at,
    t1.tags
FROM latest_not_deleted_jobs t1
    LEFT JOIN last_seen_job_timestamp t2
        USING (workspace_id, job_id)
WHERE
    (t2.last_executed_at <= CURRENT_DATE() - INTERVAL 30 DAYS) OR (t2.last_executed_at IS NULL)
ORDER BY last_executed_at ASC

Painel de acompanhamento de tarefas

O painel a seguir usa tabelas do sistema para ajudá-lo a começar a monitorar seus trabalhos e integridade operacional. Ele inclui casos de uso comuns, como acompanhamento de desempenho do trabalho, monitoramento de falhas e utilização de recursos.

Para obter informações sobre como baixar o painel, consulte Monitorar custos de trabalho & desempenho com tabelas do sistema

Troubleshooting

Trabalho não está registrado na tabela lakeflow.jobs

Se um trabalho não estiver visível nas tabelas do sistema:

• O trabalho não foi modificado nos últimos 365 dias
  • Modifique qualquer um dos campos do trabalho presentes no esquema para emitir um novo registro.
• O trabalho foi criado em uma região diferente
• Criação recente de trabalhos (atraso da tabela)

Não é possível encontrar um trabalho visto na job_run_timeline tabela

Nem todas as execuções de tarefas são visíveis em todos os lugares. Embora as entradas JOB_RUN apareçam em todas as tabelas relacionadas ao trabalho, WORKFLOW_RUN (execuções de fluxo de trabalho do notebook) são registradas apenas em job_run_timeline e SUBMIT_RUN (execuções enviadas uma vez) são registradas apenas em ambas as tabelas da linha do tempo. Essas execuções não são preenchidas em outras tabelas do sistema de trabalho, como jobs ou job_tasks.

Consulte a tabela De tipos de execução abaixo para obter um detalhamento de onde cada tipo de execução é visível e acessível.

Execução de tarefa não visível na tabela billing.usage

Em system.billing.usage, o usage_metadata.job_id só é preenchido para trabalhos executados em computação de trabalho ou computação sem servidor.

Além disso, os trabalhos WORKFLOW_RUN não têm sua própria atribuição de usage_metadata.job_id ou usage_metadata.job_run_id em system.billing.usage. Em vez disso, o uso de computação deles é atribuído ao notebook pai que os acionou. Isso significa que, quando um notebook inicia um fluxo de trabalho, todos os custos de computação aparecem como uso do notebook pai, não como um trabalho de fluxo de trabalho separado.

Consulte a referência de metadados de uso para mais informações.

Calcular o custo de um trabalho em execução em uma computação de uso geral

Não é possível calcular o custo exato de trabalhos em execução na computação para todas as finalidades com 100% de precisão. Quando um trabalho é executado em uma computação interativa (para todos os fins), várias cargas de trabalho, como notebooks, consultas SQL ou outros trabalhos, geralmente são executadas simultaneamente no mesmo recurso de computação. Como os recursos do cluster são compartilhados, não há nenhum mapeamento direto 1:1 entre os custos de computação e as execuções de trabalho individuais.

Para um acompanhamento preciso de custos de trabalho, o Databricks recomenda a execução de trabalhos em computação de trabalho dedicada ou computação sem servidor, em que o usage_metadata.job_id e usage_metadata.job_run_id permitem a atribuição de custo precisa.

Se você precisar usar a computação de todas as finalidades, poderá:

• Monitore o uso e os custos gerais do cluster em system.billing.usage com base em usage_metadata.cluster_id.
• Acompanhe as métricas de tempo de execução da tarefa separadamente.
• Considere que qualquer estimativa de custo será aproximada devido aos recursos compartilhados.

Consulte Referência de metadados de uso para obter mais informações sobre a atribuição de custo.

Valores de referência

A seção a seguir inclui referências para colunas selecionadas em tabelas relacionadas a trabalhos.

Lógica de fatiamento nas tabelas da linha do tempo

As colunas period_start_time e period_end_time nas tabelas job_run_timeline e job_task_run_timeline registram o período ativo de uma execução de trabalho ou de tarefa.

:::warning Alteração importante

A partir de 19 de janeiro de 2026, novas linhas inseridas nas tabelas cronológicas usarão uma lógica de fatiamento alinhada à hora do relógio. As linhas existentes permanecerão inalteradas.

Os segmentos são criados em intervalos de uma hora com base na hora de início da execução. Por exemplo, um trabalho a partir das 16h47 cria fatias das 16h47 às 17h47, das 17h47 às 18h47 e assim por diante.

As fatias se alinharão aos limites de hora de relógio. Por exemplo, um trabalho iniciando às 16h47 criará fatias das 16h47 às 17h, das 17h às 18h, das 18h às 19h e assim por diante. Consulte a lógica de fatiamento alinhada à hora do relógio para obter detalhes.

:::

Cada linha registra até uma hora de runtime. As execuções que durarem mais de 1 hora serão registradas em diversas linhas. Esse fatiamento garante a granularidade horária para monitorar trabalhos de execução prolongada.

Tarefas de execução curta

Para execuções com menos de 1 hora, uma única linha é emitida, com period_start_time definido como a hora de início da execução e period_end_time como a hora de término da execução.

Por exemplo, um trabalho iniciado às 12:13 UTC e encerrado às 12:45 UTC é representado por uma única linha:

Trabalhos de execução longa

Para execuções que duram mais de 1 hora, várias linhas são emitidas com o mesmo run_id, cada uma representando até uma hora da duração da execução:

• A primeira linha começa na hora de início real da execução e termina no final da primeira hora de execução.
• As linhas intermediárias (se houver) se estendem pelas janelas horárias completas, alinhadas à fatia anterior period_end_time.
• A última linha começa no início da fatia anterior e termina na hora de término real da execução.

Por exemplo, um trabalho que foi executado das 16h47 UTC às 20h28 UTC é dividido em várias linhas. Cada linha representa uma hora de atividade, exceto pela última linha, que pode ser menor:

Lógica de divisão sincronizada com o horário do relógio

A partir de 19 de janeiro de 2026, as tabelas cronológicas usam o fatiamento alinhado com a hora do relógio. Todas as fatias de tempo se alinham aos limites padrão da hora do relógio.

Para processos com menos de 1 hora que iniciam e terminam na mesma hora do relógio, uma única linha é emitida.

Para execuções de tarefas que cruzam os limites de horas cheias, várias linhas são emitidas com fatias alinhadas às horas do relógio.

• A primeira linha começa na hora de início real da execução e termina no próximo limite da hora do relógio.
• Linhas intermediárias (se houver) abrangem horas de relógio completas. Por exemplo: 14h às 15h e 15h às 16h.
• A última linha começa em um limite de hora de relógio e termina na hora de término real da execução.

Por exemplo, um trabalho executado de 1h25 UTC às 3h40 UTC é particionado em três linhas:

Valores do tipo de gatilho

job_run_timeline Na tabela, os valores possíveis para a trigger_type coluna são:

• CONTINUOUS
• CRON
• FILE_ARRIVAL
• ONETIME
• ONETIME_RETRY

Valores do tipo de execução

job_run_timeline Na tabela, os valores possíveis para a run_type coluna são:

Valores do estado do resultado

Nas tabelas job_task_run_timeline e job_run_timeline, os possíveis valores para a coluna result_state são:

Valores do código de encerramento

Nas tabelas job_task_run_timeline e job_run_timeline, os possíveis valores para a coluna termination_code são:

Valores de tipo de pipeline

pipelines Na tabela, os valores possíveis para a pipeline_type coluna são:

Referência de resultado do pipeline

pipeline_update_timeline Na tabela, os valores possíveis para a result_state coluna são:

• COMPLETED
• FAILED
• CANCELED

Referência de configurações de pipeline

pipelines Na tabela, os valores possíveis para a settings coluna são:

Valores de tipos de atualização do pipeline

pipeline_update_timeline Na tabela, os valores possíveis para a update_type coluna são:

• API_CALL
• RETRY_ON_FAILURE
• SERVICE_UPGRADE
• SCHEMA_CHANGE
• JOB_TASK
• USER_ACTION
• DBSQL_REQUEST
• SETTINGS_CHANGE
• SCHEMA_EXPLORATION
• INFRASTRUCTURE_MAINTENANCE
• START_RESOURCES

Valores de tipo de gatilho de pipeline

pipeline_update_timeline Na tabela, os valores possíveis para a trigger_type coluna são:

Detalhes sobre o tipo de gatilho de um pipeline

Na tabela pipeline_update_timeline, os valores possíveis para a estrutura trigger_type.job_task são: