INFORMATION_SCHEMA を使用した予約メタデータの取得

INFORMATION_SCHEMA は、データセット、ルーティン、テーブル、ビュー、ジョブ、予約に関するメタデータへのアクセスを提供する一連のビューです。

INFORMATION_SCHEMA 予約ビューに対してクエリを実行すると、BigQuery 予約に関するリアルタイムのメタデータを取得できます。こうしたビューには、予約、割り当て、容量コミットメントの変更点の一覧と、予約のタイムラインが含まれています。

必要な権限

INFORMATION_SCHEMA テーブルを使用して予約のメタデータを取得するには、適切に範囲を限定した権限が必要です。

  • RESERVATION_TIMELINE_BY_PROJECT にはプロジェクトの bigquery.reservations.list が必要で、BigQuery UserBigQuery Resource AdminBigQuery Admin の役割で使用できます。
  • RESERVATION_CHANGES_BY_PROJECT にはプロジェクトの bigquery.reservations.list が必要で、BigQuery UserBigQuery Resource AdminBigQuery Admin の役割で使用できます。
  • CAPACITY_COMMITMENT_CHANGES_BY_PROJECT にはプロジェクトの bigquery.capacityCommitments.list が必要で、BigQuery UserBigQuery Resource AdminBigQuery Admin の役割で使用できます。
  • ASSIGNMENT_CHANGES_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.RESERVATION_TIMELINE_BY_PROJECT は管理プロジェクト内のすべての予約のタイムライン ビューです。固有の change_timestamp ごとに、このビューにはその時点で有効なすべての予約の状態が表示されます。
  • INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES_BY_PROJECT には、管理プロジェクト内の容量コミットメントに対するすべての変更点の一覧が含まれます。各行は 1 つの容量コミットメントに対する 1 つの変更を表します。
  • INFORMATION_SCHEMA.ASSIGNMENT_CHANGES_BY_PROJECT には、管理プロジェクト内の割り当てに対するすべての変更点の一覧が含まれます。各行は 1 つの割り当てに対する 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 予約に関連付けられたスロットの容量。

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

列名 データ型
change_timestamp TIMESTAMP 変更が発生した時刻。
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 のいずれかです。

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 INTEGER 割り当て先リソースの種類。organizationfolderproject のいずれかです。
action STRING 割り当てで発生したイベントの種類。CREATE または DELETE のいずれかです。

データの保持

現在、INFORMATION_SCHEMA 予約ビューには過去 180 日間の予約履歴のみが保持されます。

地域性

BigQuery の INFORMATION_SCHEMA 予約ビューはリージョン化されています。これらのビューに対してクエリを実行するには、`region-region-name`.INFORMATION_SCHEMA.view という形式のサポートされているリージョン名を接頭辞として付ける必要があります。

例:

  • 米国マルチリージョンのデータに対してクエリを実行するには、`region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT を使用します。
  • EU マルチリージョンのデータに対してクエリを実行するには、`region-eu`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT を使用します。
  • asia-northeast1 リージョンのデータに対してクエリを実行するには、`region-asia-northeast1`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT を使用します。

使用可能なリージョンの一覧については、データセットのロケーションをご覧ください。

例 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 Web UI を開きます。

    Cloud Console に移動

  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 Web UI を開きます。

    Cloud Console に移動

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

次のステップ