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

注：

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

注：

これらのテーブルはasia-south1リージョンでは使用できません。

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

要件

• system.lakeflowスキーマは、アカウント管理者が有効にする必要があります。「システムテーブル スキーマの有効化」を参照してください。

• これらのシステムテーブルにアクセスするには、ユーザーは次のいずれかを行う必要があります。

  • メタストア管理者とアカウント管理者の両方である、または

  • システム スキーマに対する USE 権限と SELECT 権限を持っている。 システムテーブルへのアクセス権の付与を参照してください。

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

すべてのジョブ関連システムテーブルはsystem.lakeflowスキーマにあります。現在、スキーマには4つのテーブルがあります。

TABLE	説明	ストリーミングをサポート	無料保存期間	グローバルまたは地域データを含む
ジョブ (パブリック プレビュー)	アカウントで作成されたすべてのジョブを追跡します	あり	365日	リージョン
ジョブ (パブリック プレビュー)	アカウントで実行されるすべてのジョブタスクを追跡します	あり	365日	リージョン
ジョブ (パブリック プレビュー)	ジョブの実行と関連するメタデータを追跡します	あり	365日	リージョン
ジョブ (パブリック プレビュー)	ジョブタスクの実行と関連するメタデータを追跡します	あり	365日	リージョン

詳細なスキーマリファレンス

次のセクションでは、各ジョブ関連のシステムテーブルのスキーマ参照について説明します。

ジョブ テーブル スキーマ

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

テーブル パス: system.lakeflow.jobs

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

クエリの例

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

列名	データ型	説明	注
account_id	文字列	このジョブが属するアカウントの ID
workspace_id	文字列	このジョブが属するワークスペースの ID
job_id	文字列	ジョブのID	1 つのワークスペース内でのみ一意
task_key	文字列	ジョブ内のタスクの参照キー	1つのジョブ内でのみ一意
depends_on_keys	配列	このタスクのすべてのアップストリーム依存関係のタスクキー
change_time	タイムスタンプ	タスクが最後に変更された時刻	+00:00 (UTC) として記録されたタイムゾーン
delete_time	タイムスタンプ	タスクがユーザーによって削除された時刻	+00:00 (UTC) として記録されたタイムゾーン

クエリの例

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

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

クエリの例

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

列名	データ型	説明	注
account_id	文字列	このジョブが属するアカウントの ID
workspace_id	文字列	このジョブが属するワークスペースの ID
job_id	文字列	ジョブのID	1 つのワークスペース内でのみ一意
run_id	文字列	タスク実行の ID
job_run_id	文字列	ジョブランのID	2024 年 8 月下旬より前に出力された行には設定されません
parent_run_id	文字列	親実行の ID	2024 年 8 月下旬より前に出力された行には設定されません
period_start_time	タイムスタンプ	タスクまたは期間の開始時刻	タイムゾーン情報は、UTC を表す +00:00 で値の末尾に記録されます
period_end_time	タイムスタンプ	タスクまたは期間の終了時刻	タイムゾーン情報は、UTC を表す +00:00 で値の末尾に記録されます
task_key	文字列	ジョブ内のタスクの参照キー	このキーは、1 つのジョブ内でのみ一意です
compute_ids	配列	コンピュート配列には、ジョブ クラスタリング、対話型クラスタリング、およびジョブ タスクで使用される SQLウェアハウスの ID が含まれています
result_state	文字列	ジョブタスク実行の結果	使用可能な値については、結果の状態の値を参照してください
termination_code	文字列	タスク実行の終了コード	使用可能な値については、 終了コードの値を参照してください。 2024 年 8 月下旬より前に出力された行には設定されません

一般的な結合パターン

次のセクションでは、ジョブシステムテーブルで一般的に使用される結合パターンを示すサンプルクエリを示します。

ジョブ テーブルとジョブ 実行タイムライン テーブルを結合します

ジョブ名によるジョブ実行の強化

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)

ジョブ名による使用量の充実

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
  usage.*,
  coalesce(usage_metadata.job_name, jobs.name) as job_name
FROM system.billing.usage
  LEFT JOIN jobs ON usage.workspace_id=jobs.workspace_id AND usage.usage_metadata.job_id=jobs.job_id
WHERE
  billing_origin_product="JOBS"

ジョブ実行タイムラインと使用状況テーブルを結合する

各請求ログをジョブ実行メタデータで強化する

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

ジョブ タスク 実行 timeline テーブルとクラスタリング テーブルを結合する

Enrich ジョブ タスク 実行 with クラスタリング メタデータ

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
  exploded_task_runs.*,
  clusters.*
FROM exploded_task_runs t1
  LEFT JOIN clusters t2
    USING (workspace_id, cluster_id)

Find ジョブ running on all-purpose コンピュート

このクエリーは、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
),
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;

Jobs モニタリングダッシュボード

次のダッシュボードでは、システムテーブルを使用して、ジョブと運用の正常性のモニタリングを開始するのに役立ちます。 これには、ジョブのパフォーマンス追跡、障害モニタリング、リソース使用率などの一般的なユースケースが含まれます。

ダッシュボードのダウンロードに関する情報については、Monitor job costs & performance with システムテーブルを参照してください。

トラブルシューティング

ジョブがlakeflow.jobsテーブルに記録されない

ジョブがシステムテーブルに表示されない場合:

• ジョブが過去 365 日間に変更されていない

• ジョブが別のリージョンで作成されました

• 最近のジョブ作成 (テーブルラグ)

job_run_timelineテーブルに表示されるジョブが見つかりません

すべてのジョブ実行がどこでも表示されるわけではありません。 JOB_RUNエントリはすべてのジョブ関連テーブルに表示されますが、WORKFLOW_RUN (ノートブック ワークフローの実行) と SUBMIT_RUN (1 回限りの送信済み実行) はどちらもjob_run_timelineテーブルにのみ記録されます。これらの実行は、 jobs や job_tasksなどの他のジョブシステムテーブルには入力されません。

各実行タイプが表示され、アクセス可能な場所の詳細な内訳については、以下の 実行タイプの 表を参照してください。

ジョブの実行がbilling.usageテーブルに表示されない

system.billing.usageでは、ジョブ コンピュートまたはサーバレス コンピュートで実行されるジョブに対してのみusage_metadata.job_idが入力されます。

さらに、WORKFLOW_RUNジョブには、 system.billing.usageに独自のusage_metadata.job_id属性やusage_metadata.job_run_id属性はありません。代わりに、コンピュートの使用は、それらをトリガーした親ノートブックに起因します。 つまり、ノートブックがワークフロー実行を起動すると、すべてのコンピュート コストは、個別のワークフロー ジョブとしてではなく、親ノートブックの使用量の下に表示されます。

詳細については、「 使用状況メタデータの分析 」を参照してください。

万能コンピュートで実行されるジョブのコストを計算する

わざとコンピュートで動いているジョブのコスト計算は、100%の精度では不可能です。 ジョブが対話型 (汎用) コンピュートで実行される場合、ノートブック、 SQL クエリ、その他のジョブなどの複数のワークロードは、多くの場合、同じコンピュート リソースで同時に実行されます。 クラスタリング リソースは共有されるため、コンピューティング コストと個々のジョブ実行との間に直接的な 1 対 1 のマッピングはありません。

正確なジョブコスト追跡のために、 Databricks は、usage_metadata.job_idとusage_metadata.job_run_idが正確なコストの帰属を可能にする専用のジョブ コンピュートまたはサーバレス コンピュートでジョブを実行することをお勧めします。

万能コンピュートを使用する必要がある場合は、次のことができます。

• usage_metadata.cluster_idに基づいて、クラスタリングの全体的な使用量とコストを system.billing.usage で監視します。

• ジョブのランタイムメトリクスを個別に追跡します。

• コストの見積もりは、共有リソースによる概算であることを考慮してください。

コスト属性の詳細については、「 使用状況メタデータの分析 」を参照してください。

参考値

次のセクションでは、ジョブ関連テーブルの select 列の参照について説明します。

トリガーの種類の値

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

• CONTINUOUS

• CRON

• FILE_ARRIVAL

• ONETIME

• ONETIME_RETRY

実行タイプの値

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

タイプ	説明	UI の場所	API エンドポイント	システムテーブル
JOB_RUN	標準ジョブ実行	Jobs & Job 実行 UI	/ジョブおよび/ジョブ/実行エンドポイント	ジョブ, ジョブ, ジョブ, ジョブ
SUBMIT_RUN	POST /ジョブ/実行/submitによる1回限りの実行	ジョブは UI のみを実行します	/ジョブ/実行エンドポイントのみ	ジョブ
WORKFLOW_RUN	ノートブックワークフローから開始された実行	非表示	アクセス権がありません	ジョブ

結果の状態の値

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

状態	説明
SUCCEEDED	実行は正常に完了しました
FAILED	実行はエラーで完了しました
SKIPPED	条件が満たされなかったため、実行は実行されませんでした
CANCELLED	ユーザーの要求により、実行がキャンセルされました
TIMED_OUT	タイムアウトに達した後、実行が停止しました
ERROR	実行はエラーで完了しました
BLOCKED	実行がアップストリームの依存関係でブロックされました

終了コード値

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

終了コード	説明
SUCCESS	実行は正常に完了しました
CANCELLED	実行は、Databricks プラットフォームによる実行中にキャンセルされました。たとえば、最大実行時間を超えた場合などです
SKIPPED	実行が実行されなかった (たとえば、アップストリーム タスクの実行が失敗した場合、依存関係タイプの条件が満たされなかった場合、または実行するマテリアル タスクがなかった場合)
DRIVER_ERROR	Spark ドライバーとの通信中に実行でエラーが発生しました
CLUSTER_ERROR	クラスタリング エラーのため、実行に失敗しました
REPOSITORY_CHECKOUT_FAILED	サードパーティのサービスとの通信中にエラーが発生したため、チェックアウトを完了できませんでした
INVALID_CLUSTER_REQUEST	クラスタリングを開始するための無効な要求を発行したため、実行が失敗しました
WORKSPACE_RUN_LIMIT_EXCEEDED	ワークスペースが、並列 active 実行の最大数のクォータに達しました。 より長い時間枠での実行をスケジュールすることを検討してください
FEATURE_DISABLED	ワークスペースで使用できない機能にアクセスしようとしたため、実行が失敗しました
CLUSTER_REQUEST_LIMIT_EXCEEDED	クラスタリングの作成要求、開始要求、およびアップサイズ要求の数が、割り当てられたレート制限を超えました。 実行の実行をより大きな時間枠に分散することを検討します
STORAGE_ACCESS_ERROR	顧客の BLOB ストレージへのアクセス時にエラーが発生したため、実行が失敗しました
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	ジョブ・レベルのキュー・サイズ制限に達したため、実行がスキップされました