使用 INFORMATION_SCHEMA 获取预留元数据

INFORMATION_SCHEMA 是一系列视图,可让您访问数据集、例程、表、视图、作业、预留和流式数据的相关元数据。

您可以查询 INFORMATION_SCHEMA 预留视图以检索有关 BigQuery 预留的实时元数据。这些视图包含预留、分配和容量承诺更改列表,以及预留时间安排。

所需权限

如需使用 INFORMATION_SCHEMA 表检索预留元数据,您需要具备适当范围的权限:

  • RESERVATION_CHANGES_BY_PROJECTRESERVATIONS_BY_PROJECT 需要项目的 bigquery.reservations.list 权限(BigQuery UserBigQuery Resource AdminBigQuery Admin 角色具备此权限)。
  • CAPACITY_COMMITMENT_CHANGES_BY_PROJECTCAPACITY_COMMITMENTS_BY_PROJECT 需要项目的 bigquery.capacityCommitments.list 权限(BigQuery UserBigQuery Resource AdminBigQuery Admin 角色具备此权限)。
  • ASSIGNMENT_CHANGES_BY_PROJECTASSIGNMENTS_BY_PROJECT 需要项目的 bigquery.reservationAssignments.list 权限(BigQuery UserBigQuery Resource AdminBigQuery Admin 角色具备此权限)。

架构

查询 INFORMATION_SCHEMA 预留视图时,查询结果包含有关 BigQuery 预留的信息。 如需详细了解 BigQuery 预留,请参阅预留概念页面。

  • INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT 包含对管理项目中预留进行的所有更改的列表。每一行代表对单个预留进行的一项更改。
  • INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT 包含管理项目中所有当前预留的列表。每一行代表一个当前预留。当前预留是指尚未删除的预留。
  • INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES_BY_PROJECT 包含对管理项目中容量承诺进行的所有更改的列表。每一行代表对单个容量承诺进行的一项更改。
  • INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECT 包含管理项目中所有当前的容量承诺的列表。每一行代表一个当前容量承诺。当前容量承诺处于待处理或活跃状态,尚未删除。
  • INFORMATION_SCHEMA.ASSIGNMENT_CHANGES_BY_PROJECT 包含对管理项目中的分配进行的所有更改的列表。每一行代表对单个分配进行的一项更改。
  • INFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECT 包含管理项目中所有当前分配的列表。每一行代表一个当前分配。当前分配处于待处理或活跃状态,且尚未删除。

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

列名 数据类型
change_timestamp TIMESTAMP 此项更改发生的时间。
project_id STRING 管理项目的 ID。
project_number INTEGER 管理项目的编号。
reservation_name STRING 用户提供的预留名称。
ignore_idle_slots BOOL 如果为 false,则使用此预留的任何查询都可以使用其他容量承诺中未被使用的空闲槽。
action STRING 预留发生的事件类型。可以是 CREATEUPDATEDELETE
slot_capacity INTEGER 与预留关联的槽容量。
user_email STRING 进行更改的用户的电子邮件地址。google(适用于 Google 所做的更改)。如果电子邮件地址未知,则为 NULL

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

列名 数据类型
project_id STRING 管理项目的 ID。
project_number INTEGER 管理项目的编号。
reservation_name STRING 用户提供的预留名称。
ignore_idle_slots BOOL 如果为 false,则使用此预留的任何查询都可以使用其他容量承诺中未被使用的空闲槽。
slot_capacity INTEGER 与预留关联的槽容量。

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

列名 数据类型
change_timestamp TIMESTAMP 此项更改发生的时间。
project_id STRING 管理项目的 ID。
project_number INTEGER 管理项目的编号。
capacity_commitment_id STRING 唯一标识容量承诺的 ID。
commitment_plan STRING 容量承诺的承诺使用合约方案。
state STRING 容量承诺所处的状态。可以是 PENDINGACTIVE
slot_count INTEGER 与容量承诺关联的槽计数。
action STRING 容量承诺发生的事件类型。可以是 CREATEUPDATEDELETE
user_email STRING 进行更改的用户的电子邮件地址。google(适用于 Google 所做的更改)。如果电子邮件地址未知,则为 NULL
commitment_start_time TIMESTAMP 当前承诺期的开始时间。仅适用于 ACTIVE 容量承诺,否则为 NULL
commitment_end_time TIMESTAMP 当前承诺期的结束时间。仅适用于 ACTIVE 容量承诺,否则为 NULL
failure_status RECORD 对于 FAILED 承诺方案,请提供失败原因,否则为 NULLRECORDcodemessage 组成。
renewal_plan STRING 此容量承诺在 commitment_end_time 过后转换为的方案。更改方案后,系统会根据承诺方案延长承诺期。仅适用于 ANNUALTRIAL 承诺,否则为 NULL

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

列名 数据类型
project_id STRING 管理项目的 ID。
project_number INTEGER 管理项目的编号。
capacity_commitment_id STRING 唯一标识容量承诺的 ID。
commitment_plan STRING 容量承诺的承诺使用合约方案。
state STRING 容量承诺所处的状态。可以是 PENDINGACTIVE
slot_count INTEGER 与容量承诺关联的槽计数。

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

列名 数据类型
change_timestamp TIMESTAMP 此项更改发生的时间。
project_id STRING 管理项目的 ID。
project_number INTEGER 管理项目的编号。
assignment_id STRING 唯一标识分配的 ID。
reservation_name STRING 分配使用的预留的名称。
job_type STRING 可以使用该预留的作业的类型。可以是 PIPELINEQUERY
assignee_id STRING 唯一标识分配对象资源的 ID。
assignee_number INTEGER 唯一标识分配对象资源的编号。
assignee_type STRING 分配对象资源的类型。可以是 organizationfolderproject
action STRING 分配发生的事件类型。可以是 CREATEDELETE
user_email STRING 进行更改的用户的电子邮件地址。google(适用于 Google 所做的更改)。如果电子邮件地址未知,则为 NULL
state STRING 分配的状态。 可以是 PENDINGACTIVE

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

列名 数据类型
project_id STRING 管理项目的 ID。
project_number INTEGER 管理项目的编号。
assignment_id STRING 唯一标识分配的 ID。
reservation_name STRING 分配使用的预留的名称。
job_type STRING 可以使用该预留的作业的类型。可以是 PIPELINEQUERY
assignee_id STRING 唯一标识分配对象资源的 ID。
assignee_number INTEGER 唯一标识分配对象资源的编号。
assignee_type STRING 分配对象资源的类型。可以是 organizationfolderproject

数据保留

当前的预留、容量承诺和分配将保留在预留视图中,直到被删除为止。删除的预留、容量承诺和分配将分别保留在 RESERVATION_CHANGES_BY_PROJECTCAPACITY_COMMITMENT_CHANGES_BY_PROJECTASSIGNMENT_CHANGES_BY_PROJECT 视图中,最多可以保留 41 天,到期即从视图中删除。

区域性

BigQuery 的 INFORMATION_SCHEMA 预留视图已地区化。如要查询这些视图,请务必使用地区限定符

在预留视图和作业视图之间执行联接

作业视图包含 reservation_id 列。如果作业在已分配预留的项目中运行,reservation_id 将采用以下格式:reservation-admin-project:reservation-location.reservation-name

如需在预留视图和作业视图之间执行联接,您可以在作业视图列 reservation_id 和预留视图列 project_idreservation_name 之间执行联接;请参阅此示例

示例

示例 1

以下示例获取了项目当前分配的预留及其槽容量。通过将项目的槽使用量与分配给该项目的预留的槽容量进行比较来调试作业性能时,此信息会非常实用。

查询应在预留所属的管理项目上运行。 如需对非默认项目运行查询,请按 `project-id`.`region-region-name`.INFORMATION_SCHEMA.view 格式添加项目 ID, 例如 `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT

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

控制台

  1. 在 Cloud Console 中,打开 BigQuery 页面。

    转到 BigQuery 页面

  2. 查询编辑器框中,输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 Cloud Console 中的默认语法。

    SELECT
      reservation.reservation_name,
      reservation.slot_capacity
    FROM
      `reservation-admin-project.region-us`.
      INFORMATION_SCHEMA.ASSIGNMENT_CHANGES_BY_PROJECT assignment
    INNER JOIN
      `reservation-admin-project.region-us`.
      INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT AS reservation
    ON
      (assignment.reservation_name = reservation.reservation_name)
    WHERE
      assignment.action = "CREATE"
      AND assignment.assignee_id = "my-project"
      AND job_type = "QUERY" /* can also be "PIPELINE */
    ORDER BY
      assignment.change_timestamp DESC,
      reservation.change_timestamp DESC
    LIMIT
      1;
    
  3. 点击运行

gcloud

使用 query 命令并通过 --nouse_legacy_sql--use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询,请输入以下命令:

bq query --nouse_legacy_sql \
'SELECT
  reservation.reservation_name,
  reservation.slot_capacity
FROM
  `reservation-admin-project.region-us`.
  INFORMATION_SCHEMA.ASSIGNMENT_CHANGES_BY_PROJECT assignment
INNER JOIN
  `reservation-admin-project.region-us`.
  INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT AS reservation
ON
  (assignment.reservation_name = reservation.reservation_name)
WHERE
  assignment.action = "CREATE"
  AND assignment.assignee_id = "my-project"
  AND job_type = "QUERY" /* can also be "PIPELINE */
ORDER BY
  assignment.change_timestamp DESC,
  reservation.change_timestamp DESC
LIMIT
  1;'

示例 2

以下示例获取了指定预留的更改历史记录。可以使用此信息查看对特定预定进行的更改列表。

如需对非默认项目运行查询,请按 `project-id`.`region-region-name`.INFORMATION_SCHEMA.view 格式添加项目 ID, 例如 `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT

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

控制台

  1. 在 Cloud Console 中,打开 BigQuery 页面。

    转到 BigQuery 页面

  2. 查询编辑器框中,输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 Cloud Console 中的默认语法。

    SELECT
      *
    FROM
      `reservation-admin-project.region-us`.
      INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT
    WHERE
      reservation_name = "..."
    ORDER BY
      change_timestamp DESC;
    
  3. 点击运行

gcloud

使用 query 命令并通过 --nouse_legacy_sql--use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询,请输入以下命令:

bq query --nouse_legacy_sql \
'SELECT
  *
FROM
  `reservation-admin-project.region-us`.
  INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT
WHERE
  reservation_name = "..."
ORDER BY
  change_timestamp DESC;'

示例 3

以下示例在 JOBS_BY_PROJECT 视图与 RESERVATIONS_BY_PROJECT 视图之间执行联接,这些视图提供给定分配对象项目在过去一小时内的槽用量以及给定管理项目中每个预留的槽容量。分配对象项目是被分配了预留的项目,管理项目是包含预留的项目。如需了解详情,请参阅预留文档。此查询使用 RESERVATIONS_BY_PROJECT 视图获取预留信息;如果预留在过去一小时内发生了变化,reservation_slot_capacity 列可能不准确。

查询应使用包含预留的管理项目或分配对象项目来运行。如需对非默认项目运行查询,请按 `project-id`.`region-region-name`.INFORMATION_SCHEMA.view 格式添加项目 ID,例如 `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT

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

控制台

  1. 在 Cloud Console 中,打开 BigQuery 页面。

    转到 BigQuery 页面

  2. 查询编辑器字段中,输入以下标准 SQL 查询。INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 Cloud Console 中的默认语法。

     WITH
      job_data AS (
      SELECT
        job.reservation_id,
        job.total_slot_ms
      FROM
        `assignee-project.region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT AS job
      WHERE
        job.start_time < TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) )
    SELECT
      reservation.reservation_name AS reservation_name,
      ANY_VALUE(reservation.slot_capacity) AS reservation_slot_capacity,
      SUM(job.total_slot_ms) / (1000 * 60 * 60) AS avg_slots_used_by_hour
    FROM
      job_data AS job
    INNER JOIN
      `admin-project.region-us`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT AS reservation
    ON
      (job.reservation_id = CONCAT(reservation.project_id, ":", "US", ".", reservation.reservation_name))
    GROUP BY
      1
    ORDER BY
      1 DESC;
    
  3. 点击运行

gcloud

使用 query 命令并通过 --nouse_legacy_sql--use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询,请输入以下命令:

bq query --nouse_legacy_sql \
'WITH
   job_data AS (
   SELECT
     job.reservation_id,
     job.total_slot_ms
   FROM
     `assignee-project.region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT AS job
   WHERE
     job.start_time < TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) )
 SELECT
   reservation.reservation_name AS reservation_name,
   ANY_VALUE(reservation.slot_capacity) AS reservation_slot_capacity,
   SUM(job.total_slot_ms) / (1000 * 60 * 60) AS avg_slots_used_by_hour
 FROM
   job_data AS job
 INNER JOIN
   `admin-project.region-us`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT AS reservation
 ON
   (job.reservation_id = CONCAT(reservation.project_id, ":", "US", ".", reservation.reservation_name))
 GROUP BY
   1
 ORDER BY
   1 DESC;'

后续步骤