ジョブ システム テーブル リファレンス

重要

このシステム テーブルは パブリック プレビュー にあります。 テーブルにアクセスするには、 system カタログでスキーマを有効にすることが必要です。 詳細については、「システム テーブル スキーマを有効にする」を参照してください。

Note

lakeflow スキーマは、以前は workflow と呼れていました。 両方のスキーマの内容は同じです。 lakeflow スキーマを表示するには、個別に有効にする必要があります。

この記事では、lakeflow システム テーブルを使ってアカウント内のジョブを監視する方法のリファレンスを提供します。 これらのテーブルには、同じクラウド リージョン内にデプロイされたアカウント内のすべてのワークスペースのレコードが含まれます。 別のリージョンのレコードを確認するには、そのリージョンにデプロイされているワークスペースのテーブルを表示する必要があります。

system.lakeflow は、アカウント管理者が有効にする必要があります。SystemSchemas API を使用して、これを有効にすることができます。

ジョブ コストと正常性の監視のためのこれらのテーブルの使用例については、「システム テーブルを使ってジョブ コストを監視する」をご覧ください。

使用可能なジョブ テーブル

ジョブ関連のすべてのシステム テーブルは、system.lakeflow スキーマに含まれます。 現在、このスキーマによって、次の 4 つのテーブルがホストされています。

• jobs: ジョブの作成、削除に加え、ジョブの基本情報を追跡します。
• job_tasks: ジョブ タスクの作成、削除に加え、ジョブの基本情報を追跡します。
• job_run_timeline: ジョブ実行の開始、終了に加え、ジョブ実行の結果の状態を記録します。
• job_task_run_timeline: ジョブ タスクの開始、終了に加え、ジョブ実行の結果の状態を記録します。

ジョブ テーブル スキーマ

jobs テーブルは、緩やかに変化するディメンション テーブルです。 行が変更されると、新しい行が出力され、前の行が論理的に置き換えられます。

テーブル パス: このシステム テーブルは、 system.lakeflow.jobsにあります。

列名	データ型	Description
account_id	string	このジョブが属しているアカウントの ID。
workspace_id	string	このジョブが属しているワークスペースの ID。
job_id	string	ジョブの ID。 このキーは、1 つのワークスペース内でのみ一意です。
name	string	ジョブのユーザー指定の名前。
description	string	ジョブのユーザー指定の説明。 2024 年 8 月下旬より前に出力された行には事前設定されません。
creator_id	string	ジョブを作成したプリンシパルの ID。
tags	string	このジョブに関連付けられているユーザー指定のカスタム タグ。
change_time	timestamp	ジョブが最後に変更された日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。
delete_time	timestamp	ユーザーによってジョブが削除された日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。
run_as	string	ジョブの実行に使うアクセス許可を持つユーザーまたはサービス プリンシパルの ID。

ジョブのタスク テーブル スキーマ

ジョブ タスク テーブルは、緩やかに変化するディメンション テーブルです。 行が変更されると、新しい行が出力され、前の行が論理的に置き換えられます。

テーブル パス: このシステム テーブルは、 system.lakeflow.job_tasksにあります。

列名	データ型	Description
account_id	string	このジョブが属しているアカウントの ID。
workspace_id	string	このジョブが属しているワークスペースの ID。
job_id	string	ジョブの ID。 このキーは、1 つのワークスペース内でのみ一意です。
task_key	string	ジョブ内のタスクのリファレンス キー。 このキーは、1 つのジョブ内でのみ一意です。
depends_on_keys	配列	このタスクのすべてのアップストリーム依存関係のタスク キー。
change_time	timestamp	タスクが最後に変更された日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。
delete_time	timestamp	ユーザーによってタスクが削除された日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。

ジョブ実行のタイムライン テーブル スキーマ

ジョブ実行タイムライン テーブルは変更不可であり、作成時に完了します。

テーブル パス: このシステム テーブルは、 system.lakeflow.job_run_timelineにあります。

列名	データ型	Description
account_id	string	このジョブが属しているアカウントの ID。
workspace_id	string	このジョブが属しているワークスペースの ID。
job_id	string	ジョブの ID。 このキーは、1 つのワークスペース内でのみ一意です。
run_id	string	ジョブ実行の ID。
period_start_time	timestamp	実行または期間の開始日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。
period_end_time	timestamp	実行または期間の終了日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。
trigger_type	string	実行を起動できるトリガーの種類。 使用可能な値については、「トリガーの種類の値」を参照してください。
run_type	string	ジョブ実行の種類。 使用可能な値については、「Run の種類の値」を参照してください。
run_name	string	このジョブ実行に関連付けられているユーザー指定の実行名。
compute_ids	配列	親ジョブ実行のコンピューティング ID を含む配列。 SUBMIT_RUNおよびWORKFLOW_RUN実行の種類で使用されるクラスターを識別するために使用します。 その他のコンピューティング情報については、 job_task_run_timeline の表を参照してください。 2024 年 8 月下旬より前に出力された行には事前設定されません。
result_state	string	ジョブ実行の結果。 使用可能な値については、「結果の状態値」を参照してください。
termination_code	string	ジョブ実行の終了コード。 使用可能な値については、「終了コード値」を参照してください。 2024 年 8 月下旬より前に出力された行には事前設定されません。
job_parameters	map	ジョブの実行で使用されるジョブ レベルのパラメーター。 2024 年 8 月下旬より前に出力された行には事前設定されません。

トリガーの種類の値

trigger_type 列に指定できる値は次のとおりです。

• CONTINUOUS
• CRON
• FILE_ARRIVAL
• ONETIME
• ONETIME_RETRY

Run の種類の値

run_type 列に指定できる値は次のとおりです。

• JOB_RUN
• SUBMIT_RUN: POST /api/2.1/jobs/runs/submit を使用して作成された 1 回限りの実行。
• WORKFLOW_RUN: ノートブックのワークフローから開始されたジョブの実行。

結果の状態値

result_state 列に指定できる値は次のとおりです。

• SUCCEEDED
• FAILED
• SKIPPED
• CANCELLED
• TIMED_OUT
• ERROR
• BLOCKED

終了コード値

termination_code 列に指定できる値は次のとおりです。

• SUCCESS
• CANCELLED
• SKIPPED
• DRIVER_ERROR
• CLUSTER_ERROR
• REPOSITORY_CHECKOUT_FAILED
• INVALID_CLUSTER_REQUEST
• WORKSPACE_RUN_LIMIT_EXCEEDED
• FEATURE_DISABLED
• CLUSTER_REQUEST_LIMIT_EXCEEDED
• STORAGE_ACCESS_ERROR
• RUN_EXECUTION_ERROR
• UNAUTHORIZED_ERROR
• LIBRARY_INSTALLATION_ERROR
• MAX_CONCURRENT_RUNS_EXCEEDED
• MAX_SPARK_CONTEXTS_EXCEEDED
• RESOURCE_NOT_FOUND
• INVALID_RUN_CONFIGURATION
• CLOUD_FAILURE
• MAX_JOB_QUEUE_SIZE_EXCEEDED

ジョブ タスク実行のタイムライン テーブル スキーマ

ジョブ タスク実行タイムライン テーブルは変更不可であり、作成時に完了します。

テーブル パス: このシステム テーブルは、 system.lakeflow.job_task_run_timelineにあります。

列名	データ型	Description
account_id	string	このジョブが属しているアカウントの ID。
workspace_id	string	このジョブが属しているワークスペースの ID。
job_id	string	ジョブの ID。 このキーは、1 つのワークスペース内でのみ一意です。
run_id	string	タスク実行の ID。
job_run_id	string	ジョブ実行の ID。 2024 年 8 月下旬より前に出力された行には事前設定されません。
parent_run_id	string	親実行の ID。 2024 年 8 月下旬より前に出力された行には事前設定されません。
period_start_time	timestamp	タスクまたは期間の開始日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。
period_end_time	timestamp	タスクまたは期間の終了日時。 タイムゾーン情報は、UTC を表す +00:00 という形式で値の末尾に記録されます。
task_key	string	ジョブ内のタスクのリファレンス キー。 このキーは、1 つのジョブ内でのみ一意です。
compute_ids	配列	ジョブ タスクによって使用されるコンピューティングの ID を含む配列。
result_state	string	ジョブ タスク実行の結果。
termination_code	string	タスク実行の終了コード。 このテーブルの下の指定可能な値を参照してください。 2024 年 8 月下旬より前に出力された行には事前設定されません。

result_state 列に指定できる値は次のとおりです。

• SUCCEEDED
• FAILED
• SKIPPED
• CANCELLED
• TIMED_OUT
• ERROR
• BLOCKED

termination_code 列に指定できる値は次のとおりです。

• SUCCESS
• CANCELLED
• SKIPPED
• DRIVER_ERROR
• CLUSTER_ERROR
• REPOSITORY_CHECKOUT_FAILED
• INVALID_CLUSTER_REQUEST
• WORKSPACE_RUN_LIMIT_EXCEEDED
• FEATURE_DISABLED
• CLUSTER_REQUEST_LIMIT_EXCEEDED
• STORAGE_ACCESS_ERROR
• RUN_EXECUTION_ERROR
• UNAUTHORIZED_ERROR
• LIBRARY_INSTALLATION_ERROR
• MAX_CONCURRENT_RUNS_EXCEEDED
• MAX_SPARK_CONTEXTS_EXCEEDED
• RESOURCE_NOT_FOUND
• INVALID_RUN_CONFIGURATION
• CLOUD_FAILURE
• MAX_JOB_QUEUE_SIZE_EXCEEDED

クエリの例

このセクションには、LakeFlow テーブルを最大限に活用するために使用できるサンプル クエリが含まれています。

• ジョブの最新バージョンを取得する
• ワークスペースごとの 1 日あたりのジョブ数
• ワークスペースごとの 1 日あたりのジョブ状態の配布
• 実行時間が最長のジョブの概要
• runSubmit (つまり、エアフロー) を介して実行されるジョブの実行時間
• ジョブ実行分析
• All-Purpose Compute で実行されているジョブ
• 再試行されたジョブ実行

ジョブの最新バージョンを取得する

jobs テーブルと job_tasks テーブルは緩やかに変化するため、変更が行われるたびに新しいレコードが作成されます。 ジョブの最新バージョンを取得するには、change_time 列ごとに並べます。

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

ワークスペースごとの 1 日あたりのジョブ数

このクエリを実行すると、過去 7 日間の 1 日あたりのジョブ数をワークスペースごとに取得できます。

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

ワークスペースごとの 1 日あたりのジョブ状態の配布

このクエリは、ジョブ実行の結果によって過去 7 日間に配布された 1 日あたりのジョブ数をワークスペースごとに返します。 クエリを実行すると、ジョブが保留状態または実行状態になっているレコードがすべて削除されます。

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

実行時間が最長のジョブの概要

このクエリは、ジョブ実行の平均時間を秒単位で返します。 レコードはジョブごとに構成されます。 上位 90 と 95 パーセンタイルの列は、ジョブの最長実行時間の平均時間を示します。

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
),
most_recent_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
    t1.workspace_id,
    t1.job_id,
    first(t2.name, TRUE) as name,
    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
    LEFT OUTER JOIN most_recent_jobs t2 USING (workspace_id, job_id)
GROUP BY ALL
ORDER BY mean_seconds DESC
LIMIT 100

runSubmit (つまり、エアフロー) を介して実行されるジョブの実行時間

このクエリを実行すると、run_name パラメーターに基づいて特定のジョブの履歴ランタイムが指定されます。 クエリが機能するようにするには、run_name を設定する必要があります。

また、分析対象の時間の長さを編集するには、INTERVAL 60 DAYS セクションで日数を更新します。

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

ジョブ実行分析

このクエリを実行すると、特定のジョブの履歴ランタイムが指定されます。 クエリが機能するようにするには、workspace_id と job_id を設定する必要があります。

また、分析対象の時間の長さを編集するには、INTERVAL 60 DAYS セクションで日数を更新します。

with job_run_duration as (
    SELECT
        workspace_id,
        job_id,
        run_id,
        min(period_start_time) as run_start,
        max(period_start_time) as run_end,
        CAST(SUM(period_end_time - period_start_time) AS LONG) as duration,
        FIRST(result_state, TRUE) as result_state
    FROM
        system.lakeflow.job_run_timeline
    WHERE
      period_start_time > CURRENT_TIMESTAMP() - INTERVAL 60 DAYS
      AND workspace_id={workspace_id}
      AND job_id={job_id}
    GROUP BY ALL
    ORDER BY run_start DESC
),
most_recent_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
    t1.workspace_id,
    t1.job_id,
    t2.name,
    t1.run_id,
    t1.run_start,
    t1.run_end,
    t1.duration,
    t1.result_state
FROM job_run_duration t1
    LEFT OUTER JOIN most_recent_jobs t2 USING (workspace_id, job_id)

All-Purpose Compute で実行されているジョブ

このクエリは、compute.clusters システム テーブルと結合し、Jobs Compute ではなく All-Purpose Compute で実行されている最近のジョブを返します。

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

再試行されたジョブ実行

このクエリは、再試行されたジョブ実行のリストと、各実行の再試行回数を収集します。

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;