JOBS_BY_FOLDER ビュー

INFORMATION_SCHEMA.JOBS_BY_FOLDER ビューは、現在のプロジェクトの親フォルダで送信されたすべてのジョブ（その下のサブフォルダのジョブを含む）に関するニア リアルタイムのメタデータを含みます。

必要なロール

INFORMATION_SCHEMA.JOBS_BY_FOLDER ビューをクエリするために必要な権限を取得するには、親フォルダに対する BigQuery リソース閲覧者（roles/bigquery.resourceViewer）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。

この事前定義ロールには、INFORMATION_SCHEMA.JOBS_BY_FOLDER ビューにクエリを実行するために必要な bigquery.jobs.listAll 権限が含まれています。

カスタムロールや他の事前定義ロールを使用して、この権限を取得することもできます。

BigQuery の権限の詳細については、IAM でのアクセス制御をご覧ください。

スキーマ

基になるデータは creation_time 列で分割され、project_id と user_email でクラスタ化されます。query_info 列には、クエリジョブに関する追加情報が含まれます。

INFORMATION_SCHEMA.JOBS_BY_FOLDER ビューのスキーマは次のとおりです。

列名	データの種類	値
bi_engine_statistics	RECORD	プロジェクトが BI Engine SQL インターフェースを使用するように構成されている場合、このフィールドには BiEngineStatistics が含まれます。それ以外の場合は NULL になります。
cache_hit	BOOLEAN	このジョブのクエリ結果がキャッシュから取得されたかどうか。マルチクエリ ステートメント ジョブがある場合、親クエリの cache_hit は NULL です。
creation_time	TIMESTAMP	（パーティショニング列）このジョブの作成時間。パーティショニングは、このタイムスタンプの UTC 時間に基づきます。
destination_table	RECORD	結果の宛先テーブル（ある場合）。
end_time	TIMESTAMP	このジョブの終了時間（エポックからのミリ秒）。このフィールドは、ジョブが DONE 状態になった時刻を表します。
error_result	RECORD	ErrorProto オブジェクトとしてのエラーの詳細。
folder_numbers	REPEATED INTEGER	プロジェクトを含むフォルダの番号 ID。プロジェクトを直接含むフォルダから始まり、子フォルダを含むフォルダというように続きます。たとえば、folder_numbers が [1, 2, 3] の場合、フォルダ 1 にはプロジェクトが直接含まれ、フォルダ 2 には 1 が含まれ、フォルダ 3 には 2 が含まれます。この列は、JOBS_BY_FOLDER にのみ入力されます。
job_id	STRING	ジョブの ID。例: bquxjob_1234
job_stages	RECORD	ジョブのクエリステージ。 注: 行レベルのアクセス ポリシーが適用されたテーブルから読み取るクエリでは、この列の値が空になります。詳細については、BigQuery での行レベルのセキュリティに関するベスト プラクティスをご覧ください。
job_type	STRING	ジョブのタイプ。QUERY、LOAD、EXTRACT、COPY、または NULL のいずれかです。NULL の値は、スクリプト ジョブ ステートメントの評価やマテリアライズド ビューの更新などの内部ジョブを示します。
labels	RECORD	Key-Value ペアとしてジョブに適用されるラベルの配列。
parent_job_id	STRING	親ジョブの ID（存在する場合）。
priority	STRING	このジョブの優先度。有効な値として、INTERACTIVE、BATCH があります。
project_id	STRING	（クラスタリング列）プロジェクトの ID。
project_number	INTEGER	プロジェクトの数。
query	STRING	SQL クエリテキスト。JOBS_BY_PROJECT ビューにのみクエリ列があります。
referenced_tables	RECORD	ジョブによって参照されるテーブルの配列。キャッシュヒットではないクエリジョブに対してのみデータが入力されます。
reservation_id	STRING	このジョブに割り当てられたプライマリ予約の名前（形式: RESERVATION_ADMIN_PROJECT:RESERVATION_LOCATION.RESERVATION_NAME）。 この出力で: RESERVATION_ADMIN_PROJECT: 予約を管理する Google Cloud プロジェクトの名前 RESERVATION_LOCATION: 予約のロケーション RESERVATION_NAME: 予約の名前
session_info	RECORD	ジョブが実行されているセッションの詳細（存在する場合）。（プレビュー）
start_time	TIMESTAMP	このジョブの開始時間（エポックからのミリ秒）。このフィールドは、ジョブが PENDING 状態から RUNNING 状態または DONE 状態へ移行した時間を表します。
state	STRING	ジョブの実行状態。有効な状態は PENDING、RUNNING、DONE です。
statement_type	STRING	クエリ ステートメントのタイプ。たとえば、DELETE、INSERT、SCRIPT、SELECT、UPDATE です。有効な値の一覧については QueryStatementType をご覧ください。
timeline	RECORD	ジョブのクエリ タイムライン。クエリ実行のスナップショットが格納されます。
total_bytes_billed	INTEGER	オンデマンド料金を使用するようにプロジェクトが構成されている場合、このフィールドにはジョブに対して課金された合計バイト数が含まれます。プロジェクトが定額料金を使用するように構成されている場合、バイト数は課金されず、このフィールドは情報提供のみを目的としています。 注: 行レベルのアクセス ポリシーが適用されたテーブルから読み取るクエリでは、この列の値が空になります。詳細については、BigQuery での行レベルのセキュリティに関するベスト プラクティスをご覧ください。
total_bytes_processed	INTEGER	ジョブによって処理された合計バイト数。 注: 行レベルのアクセス ポリシーが適用されたテーブルから読み取るクエリでは、この列の値が空になります。詳細については、BigQuery での行レベルのセキュリティに関するベスト プラクティスをご覧ください。
total_modified_partitions	INTEGER	ジョブによって変更されたパーティションの合計数。このフィールドは、LOAD ジョブと QUERY ジョブで入力されます。
total_slot_ms	INTEGER	RUNNING 状態（再試行を含む）のジョブの全期間におけるスロット（ミリ秒）。
transaction_id	STRING	このジョブが実行されたトランザクションの ID（存在する場合）。（プレビュー）
user_email	STRING	（クラスタリング列）ジョブを実行したユーザーのメールアドレスまたはサービス アカウント。
query_info.resource_warning	STRING	クエリ処理中のリソース使用量がシステムの内部しきい値を超えた場合に表示される警告メッセージ。 クエリジョブが成功すると、resource_warning フィールドに値を入力できます。resource_warning を使用すると、query_hashes を使用してクエリを最適化し、同等のクエリセットのパフォーマンス トレンドのモニタリングを設定するための追加のデータポイントを取得できます。
query_info.query_hashes.normalized_literals	STRING	クエリのハッシュが含まれます。normalized_literals は、コメント、パラメータ値、UDF、リテラルを無視する 16 進数の STRING ハッシュです。 このフィールドは、キャッシュ ヒットではない GoogleSQL クエリが成功した場合に表示されます。
query_info.performance_insights	RECORD	ジョブのパフォーマンス分析情報。
query_info.optimization_details	STRUCT	ジョブの履歴ベースの最適化。
transferred_bytes	INTEGER	クロスクラウド クエリ（BigQuery Omni クロスクラウド転送ジョブなど）で転送された合計バイト数。
materialized_view_statistics	RECORD	クエリジョブで考慮されるマテリアライズド ビューの統計。（プレビュー）

データの保持

このビューには、現在実行中のジョブと過去 180 日間のジョブの履歴が含まれます。

スコープと構文

このビューに対するクエリでは、リージョン修飾子を指定する必要があります。次の表に、このビューのリージョン スコープを示します。

ビュー名	リソース スコープ	リージョン スコープ
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.JOBS_BY_FOLDER	指定したプロジェクトを含むフォルダ	REGION

次のように置き換えます。

• 省略可: PROJECT_ID: Google Cloud プロジェクトの ID。指定しない場合は、デフォルトのプロジェクトが使用されます。
• REGION: 任意のデータセット リージョン名。例: region-us

注: INFORMATION_SCHEMA ビューにクエリを実行するロケーションを指定する必要があります。クエリ実行のロケーションは、INFORMATION_SCHEMA ビューのリージョンと一致する必要があります。

注: INFORMATION_SCHEMA.JOBS_BY_FOLDER にクエリを実行してクエリジョブのコストの概算を確認する場合は、SCRIPT ステートメント タイプを除外します。こうしないと、一部の値が 2 回カウントされます。SCRIPT 行には、このジョブの一部として実行されたすべての子ジョブの概要値が含まれます。

例

次のクエリでは、指定したプロジェクトのフォルダ内のすべてのインタラクティブ ジョブのジョブ ID、作成日時、状態（PENDING、RUNNING、DONE）が表示されます。

SELECT
  job_id,
  creation_time,
  state
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS_BY_FOLDER
WHERE
  priority = 'INTERACTIVE';

注: INFORMATION_SCHEMA ビューの名前では大文字と小文字が区別されます。

次のような結果になります。

+--------------+---------------------------+---------------------------------+
| job_id       |  creation_time            |  state                          |
+--------------+---------------------------+---------------------------------+
| bquxjob_1    |  2019-10-10 00:00:00 UTC  |  DONE                           |
| bquxjob_2    |  2019-10-10 00:00:01 UTC  |  DONE                           |
| bquxjob_3    |  2019-10-10 00:00:02 UTC  |  DONE                           |
| bquxjob_4    |  2019-10-10 00:00:03 UTC  |  RUNNING                        |
| bquxjob_5    |  2019-10-10 00:00:04 UTC  |  PENDING                        |
+--------------+---------------------------+---------------------------------+

エクスポート ジョブで処理されたバイト数を取得する

次の例では、EXTRACT ジョブタイプの total_processed_bytes 値を計算します。エクスポート ジョブの割り当てについては、エクスポート ジョブの割り当てポリシーをご覧ください。処理された合計バイト数を使用して、合計使用量をモニタリングし、エクスポート ジョブが 1 日あたり 50 TB 未満になるようにできます。

SELECT
    DATE(creation_time) as day,
    project_id as source_project_id,
    SUM(total_bytes_processed) AS total_bytes_processed
 FROM
   region-us.INFORMATION_SCHEMA.JOBS_BY_PROJECT
 WHERE
    creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 8 DAY) AND CURRENT_TIMESTAMP()
    AND job_type = "EXTRACT"
GROUP BY
    day,
    source_project_id
ORDER BY
    day DESC

コピージョブの使用状況を取得する

コピージョブについては、テーブルをコピーするをご覧ください。次の例は、コピージョブの使用について示しています。

SELECT
    DATE(creation_time) as day,
    project_id as source_project_id,
CONCAT(destination_table.project_id,":",destination_table.dataset_id,".",destination_table.table_id) as destination_table,
    COUNT(job_id) AS copy_job_count
 FROM
   region-us.INFORMATION_SCHEMA.JOBS_BY_PROJECT
 WHERE
    creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 8 DAY) AND CURRENT_TIMESTAMP()
    AND job_type = "COPY"
GROUP BY
    day,
    source_project_id,
    destination_table
ORDER BY
    day DESC

クエリのパフォーマンス分析情報を表示する

次の例では、過去 30 日間に指定されたプロジェクトのフォルダから取得したパフォーマンス分析情報があるすべてのクエリジョブと、Google Cloud コンソールのクエリ実行グラフにリンクする URL を返します。

SELECT
  `bigquery-public-data`.persistent_udfs.job_url(
    project_id || ':us.' || job_id) AS job_url,
  query_info.performance_insights
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS_BY_FOLDER
WHERE
  DATE(creation_time) >= CURRENT_DATE - 30 -- scan 30 days of query history
  AND job_type = 'QUERY'
  AND state = 'DONE'
  AND error_result IS NULL
  AND statement_type != 'SCRIPT'
  AND EXISTS ( -- Only include queries which had performance insights
    SELECT 1
    FROM UNNEST(
      query_info.performance_insights.stage_performance_standalone_insights
    )
    WHERE slot_contention OR insufficient_shuffle_quota
    UNION ALL
    SELECT 1
    FROM UNNEST(
      query_info.performance_insights.stage_performance_change_insights
    )
    WHERE input_data_change.records_read_diff_percentage IS NOT NULL
  );