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 Reservations の詳細については、Reservations のコンセプト ページをご覧ください。

  • INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT には、管理プロジェクト内の予約に対するすべての変更点の一覧が含まれます。各行は 1 つの予約に対する変更を表します。
  • INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT には、管理プロジェクト内の現在のすべての予約リストが含まれます。各行は、現在の 1 つの予約を表します。現在の予約は、削除されていない予約です。
  • INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES_BY_PROJECT には、管理プロジェクト内の容量コミットメントに対するすべての変更点の一覧が含まれます。各行は 1 つの容量コミットメントに対する 1 つの変更を表します。
  • INFORMATION_SCHEMA.CAPACITY_COMMITMENTS_BY_PROJECT には、管理プロジェクト内の現在のすべての容量コミットメントの一覧が含まれます。各行は、現在の 1 つの容量コミットメントを表します。現在の容量コミットメントは、保留中またはアクティブであり、削除されていません。
  • INFORMATION_SCHEMA.ASSIGNMENT_CHANGES_BY_PROJECT には、管理プロジェクト内の割り当てに対するすべての変更点の一覧が含まれます。各行は 1 つの割り当てに対する 1 つの変更を表します。
  • INFORMATION_SCHEMA.ASSIGNMENTS_BY_PROJECT には、管理プロジェクト内の現在のすべての割り当てリストが含まれます。各行は、現在の 1 つの割り当てを表します。現在の割り当ては、保留中またはアクティブであり、削除されていません。

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 予約で発生したイベントの種類。CREATEUPDATE、または DELETE のいずれかです。
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 容量コミットメントの状態。PENDING または ACTIVE のいずれかです。
slot_count INTEGER 容量コミットメントに関連付けられたスロット数。
action STRING 容量コミットメントで発生したイベントの種類。CREATEUPDATE、または DELETE のいずれかです。
user_email STRING 変更を行ったユーザーのメールアドレス。Google による変更の場合は google。メールアドレスが不明な場合は NULL
commitment_start_time TIMESTAMP 現在のコミットメント期間が開始する日時。ACTIVE の容量コミットメントにのみ適用されます。それ以外の場合は NULL になります。
commitment_end_time TIMESTAMP 現在のコミットメント期間が終了する日時。ACTIVE の容量コミットメントにのみ適用されます。それ以外の場合は NULL になります。
failure_status RECORD FAILED コミットメント プランの場合は、失敗の理由を示します。それ以外の場合は NULL となります。RECORDcodemessage で構成されています。
renewal_plan STRING この容量コミットメントが commitment_end_time 経過後に変換されるプラン。プランが変更された後、コミットメント プランに従って commit 期間が延長されます。ANNUAL コミットメントと TRIAL コミットメントにのみ適用されます。それ以外の場合は NULL になります。

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

列名 データ型
project_id STRING 管理プロジェクトの ID。
project_number INTEGER 管理プロジェクトの番号。
capacity_commitment_id STRING 容量コミットメントを一意に識別する ID。
commitment_plan STRING 容量コミットメントのコミットメント プラン。
state STRING 容量コミットメントの状態。PENDING または ACTIVE のいずれかです。
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 予約に使用できるジョブの種類。PIPELINE または QUERY のいずれかです。
assignee_id STRING 割り当て先リソースを一意に識別する ID。
assignee_number INTEGER 割り当て先リソースを一意に識別する番号。
assignee_type STRING 割り当て先リソースの種類。organizationfolderproject のいずれかです。
action STRING 割り当てで発生したイベントの種類。CREATE または DELETE のいずれかです。
user_email STRING 変更を行ったユーザーのメールアドレス。Google による変更の場合は google。メールアドレスが不明な場合は NULL
state STRING 割り当てのステータス。PENDING または ACTIVE のいずれかです。

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

列名 データ型
project_id STRING 管理プロジェクトの ID。
project_number INTEGER 管理プロジェクトの番号。
assignment_id STRING 割り当てを一意に識別する ID。
reservation_name STRING 割り当てが使用する予約の名前。
job_type STRING 予約に使用できるジョブの種類。PIPELINE または QUERY のいずれかです。
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_id および reservation_name の間で結合を行います。こちらの例をご覧ください。

例 1

次の例では、プロジェクトに現在割り当てられている予約とそのスロット容量を取得します。この情報は、プロジェクトのスロットの使用状況をそのプロジェクトに割り当てられている予約の容量と比較して、ジョブのパフォーマンスをデバッグする場合に役立ちます。

このクエリは、予約が含まれている管理プロジェクトで実行する必要があります。デフォルト プロジェクト以外のプロジェクトに対してクエリを実行するには、次の形式でプロジェクト ID を追加します: `project-id`.`region-region-name`.INFORMATION_SCHEMA.view。例: `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT

クエリを実行するには:

Console

  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

次の例では、特定の予約の変更履歴を取得します。この情報を使用して、特定の予約に対する変更点の一覧を表示します。

デフォルト プロジェクト以外のプロジェクトに対してクエリを実行するには、次の形式でプロジェクト ID を追加します: `project-id`.`region-region-name`.INFORMATION_SCHEMA.view。例: `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT

クエリを実行するには:

Console

  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

次の例では、過去 1 時間の特定の割り当て先によるスロット使用量と、特定の管理プロジェクトにおける各予約のスロット容量の両方を示す JOBS_BY_PROJECT ビューおよび RESERVATIONS_BY_PROJECT ビューを結合しています。割り当て先プロジェクトは、予約が割り当てられたプロジェクトであり、管理プロジェクトは予約を含むプロジェクトです。詳細については、予約に関するドキュメントをご覧ください。このクエリは、RESERVATIONS_BY_PROJECT ビューを使用して予約情報を取得します。予約に対して過去 1 時間に変更が加えられた場合、reservation_slot_capacity 列は正確でない可能性があります。

クエリは、予約または割り当て先プロジェクトを含む管理プロジェクトを使用して実行する必要があります。デフォルト プロジェクト以外のプロジェクトに対してクエリを実行するには、次の形式でプロジェクト ID を追加します。`project-id`.`region-region-name`.INFORMATION_SCHEMA.view。例: `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATIONS_BY_PROJECT

クエリを実行するには:

Console

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

次のステップ