JOBS_BY_FOLDER 视图

INFORMATION_SCHEMA.JOBS_BY_FOLDER 视图包含有关当前项目的父文件夹中提交的所有作业（包括其下子文件夹中的作业）的近乎实时元数据。

所需角色

如需获得查询 INFORMATION_SCHEMA.JOBS_BY_FOLDER 视图所需的权限，请让您的管理员为您授予父级文件夹的 BigQuery Resource Viewer (roles/bigquery.resourceViewer) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供 bigquery.jobs.listAll 权限，查询 INFORMATION_SCHEMA.JOBS_BY_FOLDER 视图需要该权限。

您也可以使用自定义角色或其他预定义角色来获取此权限。

如需详细了解 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_creation_reason.code	STRING	指定创建作业的概要原因。 可能的值包括： REQUESTED：已请求创建作业。 LONG_RUNNING：查询请求运行超出 QueryRequest 中的 timeoutMs 字段指定的系统定义超时时间。因此，查询被视为为其创建作业的长时间运行的操作。 LARGE_RESULTS：查询结果无法放入内嵌响应。 OTHER：系统已确定需要将查询作为作业执行。
job_id	STRING	作业的 ID（如果已创建作业）。否则，该值是使用短查询模式的查询的 ID。例如 bquxjob_1234。
job_stages	RECORD	作业的查询阶段。 注意：对于从具有行级访问权限政策的表中读取的查询，此列的值为空。如需了解详情，请参阅 BigQuery 中行级安全性的最佳实践。
job_type	STRING	作业的类型。可以是 QUERY、LOAD、EXTRACT、COPY 或 NULL。NULL 值表示内部作业，例如脚本作业语句评估或物化视图刷新。
labels	RECORD	作为键值对应用于作业的标签数组。
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：预留的名称
edition	STRING	与分配给此作业的预留关联的版本。如需详细了解版本，请参阅 BigQuery 版本简介。
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 是一个十六进制 STRING 哈希值，忽略注释、参数值、UDF 和字面量。如果底层视图发生变化，或者查询隐式引用列（例如 SELECT *）且表架构发生变化，则哈希值会有所不同。 系统会对非缓存命中的成功 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 语句类型，否则某些值可能会被计入两次。SCRIPT 行包含在此作业中执行的所有子作业的汇总值。

示例

以下查询会显示指定项目文件夹中所有交互式作业的作业 ID、创建时间和状态（PENDING、RUNNING 或 DONE）：

SELECT
  job_id,
  creation_time,
  state
FROM
  `region-REGION_NAME`.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 值。如需了解导出作业的配额，请参阅导出作业的配额政策。处理的总字节数可用于监控总用量，并确保导出作业的总用量保持在每天 50 TB 以下：

SELECT
    DATE(creation_time) as day,
    project_id as source_project_id,
    SUM(total_bytes_processed) AS total_bytes_processed
 FROM
   `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS
 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-REGION_NAME`.INFORMATION_SCHEMA.JOBS
 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 控制台中的查询执行图的网址。

SELECT
  `bigquery-public-data`.persistent_udfs.job_url(
    project_id || ':us.' || job_id) AS job_url,
  query_info.performance_insights
FROM
  `region-REGION_NAME`.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
  );