JOBS 视图

INFORMATION_SCHEMA.JOBS 视图包含当前项目中所有 BigQuery 作业的实时元数据。

所需权限

如需查询 INFORMATION_SCHEMA.JOBS 视图,您需要拥有项目的 bigquery.jobs.listAll Identity and Access Management (IAM) 权限。以下每个预定义的 IAM 角色均可提供所需的权限:

  • BigQuery Admin
  • BigQuery Resource Admin
  • BigQuery Resource Editor
  • BigQuery Resource Viewer

如需详细了解 BigQuery 权限,请参阅使用 IAM 进行访问权限控制

架构

底层数据按 creation_time 列进行分区,并按 project_iduser_email 进行聚簇。

INFORMATION_SCHEMA.JOBS 视图具有如下架构:

列名 数据类型
creation_time TIMESTAMP (分区列)此作业的创建时间。分区基于此时间戳的世界协调时间 (UTC)。
project_id STRING (聚簇列)项目的 ID。
project_number INTEGER 项目编号。
user_email STRING (聚簇列)运行作业的用户的电子邮件地址或服务帐号。
job_id STRING 作业的 ID。例如 bquxjob_1234
job_type STRING 作业的类型。可以是 QUERYLOADEXTRACTCOPYnull。作业类型 null 表示内部作业,例如脚本作业语句评估或具体化视图刷新。
statement_type STRING 查询语句(如果有效的话)的类型。例如 SELECTINSERTUPDATEDELETESCRIPT。如需查看有效值的列表,请参阅 QueryStatementType
priority STRING 此作业的优先级。 有效值包括 INTERACTIVEBATCH
start_time TIMESTAMP 此作业的开始时间。
end_time TIMESTAMP 此作业的结束时间。
query STRING SQL 查询文本。注意:只有 JOBS_BY_PROJECT 视图具有 query 列。
state STRING 作业的运行状态。有效状态包括 PENDINGRUNNINGDONE
reservation_id STRING 分配给此作业的主要预留的名称(如果适用的话)。如果作业在已分配给预留的项目中运行,其采用以下格式:RESERVATION_ADMIN_PROJECT:RESERVATION_LOCATION.RESERVATION_NAME

在此输出中:

  • RESERVATION_ADMIN_PROJECT:管理预留的 Google Cloud 项目的名称
  • RESERVATION_LOCATION:预留的位置
  • RESERVATION_NAME:预留的名称
total_bytes_processed INTEGER 作业处理的字节总数。
total_slot_ms INTEGER 整个作业持续时间内的的槽毫秒数。
error_result RECORD 错误的详细信息(如有),为 ErrorProto
cache_hit BOOLEAN 查询此作业的查询结果是否来自缓存。
destination_table RECORD 结果的目标(如有)。
referenced_tables RECORD 作业引用的数组。 仅针对查询作业进行填充。
labels RECORD 作为 keyvalue 字符串应用于作业的标签数组。
timeline RECORD 作业的查询时间轴。包含查询执行情况的快照。
job_stages RECORD 作业的查询阶段
total_bytes_billed INTEGER 如果项目配置为使用按需价格,则此字段包含作业的总计费字节数。如果项目配置为使用固定价格,则您无需为字节付费,并且此字段仅供参考。
parent_job_id STRING 父级作业的 ID(如有)。
transaction_id STRING 此作业在其中运行的事务的 ID(如果有)。(预览版
session_info RECORD 运行此作业的会话的详细信息(如果有)。(预览版
dml_statistics RECORD

如果作业是带有 DML 语句的查询,则值是包含以下字段的记录:

  • inserted_row_count:已插入的行数。
  • deleted_row_count:已删除的行数。
  • updated_row_count:已更新的行数。

对于所有其他作业,值为 NULL

INFORMATION_SCHEMA.JOBS_BY_USERINFORMATION_SCHEMA.JOBS_BY_PROJECT 视图中将显示此列。

bi_engine_statistics RECORD 如果项目配置为使用 BI Engine SQL 接口,则此字段包含 BiEngineStatistics。否则为 NULL
total_modified_partitions INTEGER 作业修改的分区总数。系统会针对 LOADQUERY 作业填充此字段。

数据保留

此视图包含当前正在运行的作业和过去 180 天的作业历史记录。

范围和语法

针对此视图的查询必须包含区域限定符。如果您未指定区域限定符,则会从所有区域检索元数据。下表说明了此视图的区域范围:

视图名称 资源范围 区域范围
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.JOBS[_BY_PROJECT] 项目级 REGION
替换以下内容:

  • 可选:PROJECT_ID:您的 Cloud 项目的 ID。如果未指定,则使用默认项目。
  • REGION:任何数据集区域名称。例如 region-us

当您查询 INFORMATION_SCHEMA.JOBS 以查找查询作业的汇总费用时,请排除 SCRIPT 语句类型,否则某些值会被重复计算。SCRIPT 行包含在此作业中执行的所有子作业的汇总值。

示例

如需对非默认项目运行查询,请按以下格式添加项目 ID:

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.JOBS
替换以下内容:

  • PROJECT_ID:项目的 ID。
  • REGION_NAME:项目的区域。

例如 `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT

以下示例会计算指定项目在过去 7 天内所有查询的平均槽利用率。请注意,此计算对于在一周内槽使用量一致的项目最为准确。如果项目的槽使用量不一致,则此数字可能会低于预期。

要运行查询,请执行以下操作:

SELECT
  SUM(total_slot_ms) / (1000 * 60 * 60 * 24 * 7) AS avg_slots
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  -- Filter by the partition column first to limit the amount of data scanned.
  -- Eight days allows for jobs created before the 7 day end_time filter.
  creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 8 DAY) AND CURRENT_TIMESTAMP()
  AND job_type = 'QUERY'
  AND end_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP();

结果类似于以下内容:

+------------+
| avg_slots  |
+------------+
| 3879.1534  |
+------------+

您可以使用 WHERE reservation_id = "…" 检查特定预留的使用率。这可能有助于确定预留在一段时间内的使用百分比。对于脚本作业,父级作业还会报告其子作业的总体槽使用量。为了避免重复计算,请使用 WHERE statement_type != "SCRIPT" 排除父作业。

如果您希望查看各个作业的平均槽利用率,请使用 total_slot_ms / TIMESTAMP_DIFF(end_time, start_time, MILLISECOND)

示例:加载作业历史记录

以下示例会列出针对指定项目提交批量加载作业的所有用户或服务帐号。由于未指定时间边界,因此该查询会扫描所有可用历史记录(例如,过去 30 天)。

SELECT
  DISTINCT(user_email) AS user
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  job_type = 'LOAD';

结果类似于以下内容:

+--------------+
| user         |
+--------------+
| abc@xyz.com  |
+--------------+
| def@xyz.com  |
+--------------+

示例:每个用户身份处理的字节数

以下示例显示了每个用户的查询作业结算的总字节数。

SELECT
  user_email,
  SUM(total_bytes_billed) AS bytes_billed
FROM
  `region-us.INFORMATION_SCHEMA.JOBS`
WHERE
  job_type = 'QUERY'
  AND statement_type != 'SCRIPT'
GROUP BY
  user_email;

结果应如下所示:

+---------------------+--------------+
| user_email          | bytes_billed |
+---------------------+--------------+
| bob@example.com     | 2847932416   |
| alice@example.com   | 1184890880   |
| charles@example.com | 10485760     |
+---------------------+--------------+

示例:已处理的字节数的每小时明细

以下示例显示了查询作业按小时间隔计费的总字节数:

SELECT
  TIMESTAMP_TRUNC(end_time, HOUR) AS time_window,
  SUM(total_bytes_billed) AS bytes_billed
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  job_type = 'QUERY'
  AND statement_type != 'SCRIPT'
GROUP BY
  time_window
ORDER BY
  time_window DESC

结果类似于以下内容:

+-------------------------+--------------+
| time_window             | bytes_billed |
+-------------------------+--------------+
| 2022-05-17 20:00:00 UTC | 1967128576   |
| 2022-05-10 21:00:00 UTC | 0            |
| 2022-04-15 20:00:00 UTC | 10485760     |
| 2022-04-15 17:00:00 UTC | 41943040     |
+-------------------------+--------------+