作业系统表参考

本文是 lakeflow 系统表的参考，这些系统表记录帐户中的作业活动。 这些表包括部署在同一云区域中的帐户中所有工作区的记录。 若要查看另一个区域中的记录，必须查看该区域中部署的工作区中的表。

Requirements

• 若要访问这些系统表，用户必须：
  • 既是元存储管理员，也是帐户管理员，或者
  • 对系统架构具有 USE 和 SELECT 权限。 请参阅授予对系统表的访问权限。

可用的作业表

所有与作业相关的系统表都位于架构中 system.lakeflow 。 目前，该架构托管四个表：

详细架构参考

以下各节为每个与作业相关的系统表提供架构引用。

作业表架构

jobs 表是渐变维度表（SCD2）。 当行发生更改时，系统会发出新行，以逻辑方式替换上一行。

表路径： system.lakeflow.jobs

示例查询

-- 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

作业任务表架构

作业任务表是一个渐变的维度表（SCD2）。 当行发生更改时，系统会发出新行，以逻辑方式替换上一行。

表路径： system.lakeflow.job_tasks

示例查询

-- 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

作业运行时间线表架构

作业运行时间线表是不可变的，在生成作业时完成。

表路径： system.lakeflow.job_run_timeline

示例查询

-- 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;

作业任务运行时间线表架构

作业任务运行时间线表是不可变的，在生成作业时完成。

表路径： system.lakeflow.job_task_run_timeline

管道表架构

管道表是一个渐变维度表（SCD2）。 当行发生更改时，系统会发出新行，以逻辑方式替换上一行。

表路径： system.lakeflow.pipelines

示例查询

-- 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

管道更新时间线表架构

管道更新时间线表是不可变的，在生成时完成。

表路径： system.lakeflow.pipeline_update_timeline

示例查询

-- 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

常见联接模式

以下部分提供了示例查询，这些查询突出显示了作业系统表的常用联接模式。

联接作业和作业运行时间线表

使用作业名称扩充作业运行

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)

联接作业运行时间线和使用情况表

使用作业运行元数据扩充每个计费日志

SELECT
    t1.*,
    t2.*
FROM system.billing.usage t1
    LEFT JOIN system.lakeflow.job_run_timeline t2
        ON t1.workspace_id = t2.workspace_id
            AND t1.usage_metadata.job_id = t2.job_id
            AND t1.usage_metadata.job_run_id = t2.run_id
            AND t1.usage_start_time >= date_trunc("Hour", t2.period_start_time)
            AND t1.usage_start_time < date_trunc("Hour", t2.period_end_time) + INTERVAL 1 HOUR
WHERE
    billing_origin_product="JOBS"

计算每次作业运行的成本

此查询与 billing.usage 系统表联接，以计算每个作业运行的成本。

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

获取 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
  )

联接作业任务运行时间线和群集表

使用群集元数据扩充作业任务运行

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)

查找基于通用计算运行的作业

此查询与 compute.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
  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;

查找在过去 30 天内未运行的作业

此查询联接 lakeflow.jobs 和 lakeflow.job_run_timeline 系统表以返回过去 30 天内未运行的作业。

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

作业监视仪表板

以下仪表板使用系统表来帮助您开始监控作业和运行状况。 它包括常见用例，例如作业性能跟踪、故障监视和资源利用率。

有关下载仪表板的信息，请参阅使用系统表监视作业成本和性能

Troubleshooting

作业未记录在 lakeflow.jobs 表中

如果任务在系统表中不可见：

• 在过去的 365 天内，该职位未被修改
  • 修改模式中的任何作业字段以生成新记录。
• 作业是在不同区域创建的
• 最近创建的作业（表延迟）

找不到 job_run_timeline 表中的作业

并非所有作业运行在任何地方都可见。 虽然 JOB_RUN 条目出现在所有与作业相关的表中，但 WORKFLOW_RUN（笔记本工作流运行）仅记录在 job_run_timeline 中，SUBMIT_RUN（一次性提交的运行）仅记录在这两个时间线表中。 这些运行不会填充到其他作业系统表，例如 jobs 或 job_tasks。

有关每种运行类型可见和可访问的详细细分，请参阅下面的 “运行类型 ”表。

作业运行在 billing.usage 表中不可见

在 system.billing.usage 中，仅针对在作业计算或无服务器计算上运行的作业填充 usage_metadata.job_id。

此外，WORKFLOW_RUN 作业在 usage_metadata.job_id 中没有自己的 usage_metadata.job_run_id 或 system.billing.usage 属性。 这些计算的使用量将归因于触发它们的父笔记本。 这意味着，当笔记本启动一个工作流时，所有计算成本都记录在父笔记本的使用情况中，而不是作为单独工作流任务。

有关详细信息，请参阅 使用情况元数据参考。

计算基于通用计算运行的作业的成本

无法以 100% 的准确率对基于用途计算运行的作业进行精确的成本计算。 当作业在交互式（用途）计算上运行时，多个工作负荷（如笔记本、SQL 查询或其他作业）通常会在同一计算资源上同时运行。 由于群集资源是共享的，因此计算成本和单个作业运行之间没有直接的 1：1 映射。

为了准确跟踪作业成本，Databricks 建议在专用作业计算或无服务器计算上运行作业，其中 usage_metadata.job_id 和 usage_metadata.job_run_id 允许精确的成本归因。

如果必须使用全用途计算，可以：

• 根据 system.billing.usage 监视 usage_metadata.cluster_id 中的总体群集使用情况和成本。
• 单独跟踪作业运行时指标。
• 请考虑由于共享资源，任何成本估算都将是近似值。

有关成本归因的详细信息，请参阅 使用情况元数据参考。

引用值

以下部分包括有关作业相关表中选择列的引用。

时间线表中的切片逻辑

period_start_time 和 period_end_time 表中的 job_run_timeline 和 job_task_run_timeline 列记录作业运行或任务运行的活动期限。

每行最多记录一个小时的运行时。 持续时间超过 1 小时的运行记录在多个行上。 此切片可确保监视长时间运行的作业时的每小时精细度。

运行时间较短的作业

对于短于 1 小时的运行，将发出单个行，并 period_start_time 设置为运行开始时间并 period_end_time 设置为运行结束时间。

例如，作业从 UTC 下午 12：13 开始，以 12：45 UTC 结束，由单个行表示：

长时间运行的作业

对于运行时间超过 1 小时的情况，将发出多行具有相同run_id的行，每行最多表示最长一小时的运行时长。

• 第一行从运行的实际开始时间开始，在第一个运行小时结束时结束。
• 中间行（如果有的话）跨越整个小时窗口，与前一个切片 period_end_time 对齐。
• 最后一行从上一个切片的开头开始，到运行的实际结束时间结束。

例如，一个从 UTC 下午 4:47 运行到 UTC 晚上 8:28 的作业被切成多行。 每行表示一小时的活动，最后一行除外，可能较短：

触发器类型值

在 job_run_timeline 表中，trigger_type 列的可能值为：

• CONTINUOUS
• CRON
• FILE_ARRIVAL
• ONETIME
• ONETIME_RETRY

运行类型值

在 job_run_timeline 表中，run_type 列的可能值为：

结果状态值

在job_task_run_timeline和job_run_timeline表中，result_state列的可能值为：

终止代码值

在job_task_run_timeline和job_run_timeline表中，termination_code列的可能值为：

管道类型值

在 pipelines 表中，pipeline_type 列的可能值为：

管道结果参考

在 pipeline_update_timeline 表中，result_state 列的可能值为：

• COMPLETED
• FAILED
• CANCELED

管道设置参考

在 pipelines 表中，settings 列的可能值为：

管道更新类型值

在 pipeline_update_timeline 表中，update_type 列的可能值为：

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

管道触发器类型值

在 pipeline_update_timeline 表中，trigger_type 列的可能值为：

管道触发器类型详细信息

在 pipeline_update_timeline 表中，结构的可能值为 trigger_type.job_task ：