Obtenir des métadonnées de réservation à l'aide de INFORMATION_SCHEMA

INFORMATION_SCHEMA est une série de vues donnant accès aux métadonnées sur des ensembles de données, des routines, des tables, des vues, des tâches et des réservations.

Vous pouvez récupérer les métadonnées en temps réel des réservations BigQuery en interrogeant les vues des réservations INFORMATION_SCHEMA. Ces vues contiennent une liste des modifications apportées aux réservations, aux attributions et aux engagements de capacité, ainsi qu'une chronologie des réservations.

Autorisations requises

La récupération des métadonnées de réservation à l'aide des tables INFORMATION_SCHEMA nécessite des autorisations dotées de niveaux d'accès appropriés :

  • RESERVATION_TIMELINE_BY_PROJECT nécessite l'autorisation bigquery.reservations.list pour le projet et est disponible pour les rôles BigQuery User, BigQuery Resource Admin, et BigQuery Admin.
  • RESERVATION_CHANGES_BY_PROJECT nécessite l'autorisation bigquery.reservations.list pour le projet et est disponible pour les rôles BigQuery User, BigQuery Resource Admin, et BigQuery Admin.
  • CAPACITY_COMMITMENT_CHANGES_BY_PROJECT nécessite l'autorisation bigquery.capacityCommitments.list pour le projet et est disponible pour les rôles BigQuery User, BigQuery Resource Admin, et BigQuery Admin.
  • ASSIGNMENT_CHANGES_BY_PROJECT nécessite l'autorisation bigquery.reservationAssignments.list pour le projet et est disponible pour les rôles BigQuery User, BigQuery Resource Admin, et BigQuery Admin.

Schémas

Lorsque vous interrogez les vues de réservation INFORMATION_SCHEMA, les résultats de la requête contiennent des informations sur les réservations BigQuery. Pour en savoir plus sur les réservations BigQuery, consultez la page sur les concepts de réservation.

  • INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT contient la liste de toutes les modifications apportées aux réservations dans le projet d'administration. Chaque ligne représente une modification apportée à une seule réservation.
  • INFORMATION_SCHEMA.RESERVATION_TIMELINE_BY_PROJECT est une vue chronologique de toutes les réservations dans le projet d'administration. Pour chaque change_timestamp unique, cette vue répertorie l'état de toutes les réservations actives à ce moment-là.
  • INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES_BY_PROJECT contient une liste de toutes les modifications apportées aux engagements de capacité dans le projet d'administration. Chaque ligne représente une modification apportée à un seul engagement de capacité.
  • INFORMATION_SCHEMA.ASSIGNMENT_CHANGES_BY_PROJECT contient la liste de toutes les modifications apportées aux attributions dans le projet d'administration. Chaque ligne représente une modification apportée à une seule attribution.

La vue INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT présente le schéma suivant :

Nom de la colonne Type de données Valeur
change_timestamp TIMESTAMP Heure à laquelle la modification s'est produite.
project_id STRING ID du projet d'administration.
project_number INTEGER Numéro du projet d'administration.
reservation_name STRING Nom de réservation fourni par l'utilisateur.
ignore_idle_slots BOOL Si la valeur est définie sur "false", toute requête utilisant cette réservation peut exploiter des emplacements inactifs provenant d'autres engagements de capacité.
action STRING Type d'événement survenu lors de la réservation. Il peut s'agir de CREATE, UPDATE ou DELETE.
slot_capacity INTEGER Capacité d'emplacements associée à la réservation.

La vue INFORMATION_SCHEMA.RESERVATION_TIMELINE_BY_PROJECT présente le schéma suivant :

Nom de la colonne Type de données Valeur
change_timestamp TIMESTAMP Heure à laquelle la modification s'est produite.
project_id STRING ID du projet d'administration.
project_number INTEGER Numéro du projet d'administration.
reservation_name STRING Nom de réservation fourni par l'utilisateur.
ignore_idle_slots BOOL Si la valeur est définie sur "false", toute requête utilisant cette réservation peut exploiter des emplacements inactifs provenant d'autres engagements de capacité.
slot_capacity INTEGER Capacité d'emplacements associée à la réservation.

La vue INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES_BY_PROJECT présente le schéma suivant :

Nom de la colonne Type de données Valeur
change_timestamp TIMESTAMP Heure à laquelle la modification s'est produite.
project_id STRING ID du projet d'administration.
project_number INTEGER Numéro du projet d'administration.
capacity_commitment_id STRING ID qui identifie de manière unique l'engagement de capacité.
commitment_plan STRING Forfait de l'engagement de capacité.
state STRING État de l'engagement de capacité. Il peut s'agir de PENDING ou ACTIVE.
slot_count INTEGER Nombre d'emplacements associés à l'engagement de capacité.
action STRING Type d'événement survenu avec l'engagement de capacité. Il peut s'agir de CREATE, UPDATE ou DELETE.

La vue INFORMATION_SCHEMA.ASSIGNMENT_CHANGES_BY_PROJECT présente le schéma suivant :

Nom de la colonne Type de données Valeur
change_timestamp TIMESTAMP Heure à laquelle la modification s'est produite.
project_id STRING ID du projet d'administration.
project_number INTEGER Numéro du projet d'administration.
assignment_id STRING ID qui identifie de manière unique l'attribution.
reservation_name STRING Nom de la réservation utilisée par l'attribution.
job_type STRING Type de tâche pouvant utiliser la réservation. Il peut s'agir de PIPELINE ou QUERY.
assignee_id STRING ID qui identifie de manière unique la ressource affectée.
assignee_number INTEGER Numéro qui identifie de manière unique la ressource affectée.
assignee_type INTEGER Type de ressource affectée. Il peut s'agir de organization, folder ou project.
action STRING Type d'événement survenu lors de l'attribution. Il peut s'agir de CREATE ou DELETE.

Conservation des données

Actuellement, seuls les 180 derniers jours de l'historique des réservations sont conservés dans les vues des réservations INFORMATION_SCHEMA.

Régionalité

Les vues des réservations INFORMATION_SCHEMA de BigQuery sont régionalisées. Pour interroger ces vues, vous devez ajouter un préfixe à un nom de région compatible en respectant le format suivant : `region-region-name`.INFORMATION_SCHEMA.view.

Exemple :

  • Pour interroger des données dans l'emplacement multirégional "US", utilisez `region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT.
  • Pour interroger des données dans l'emplacement multirégional "EU", utilisez `region-eu`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT.
  • Pour interroger des données dans la région asia-northeast1, utilisez `region-asia-northeast1`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT.

Pour obtenir la liste des régions disponibles, consultez la section Emplacements des ensembles de données.

Exemples

Exemple 1

Dans l'exemple suivant, on récupère la réservation actuellement attribuée au projet ainsi que sa capacité d'emplacements. Ces informations peuvent vous aider à déboguer les performances des tâches en comparant l'utilisation de l'emplacement du projet avec la capacité d'emplacements attribuée à ce même projet.

La requête doit s'exécuter sur le projet d'administration contenant les réservations. Pour exécuter la requête sur un projet autre que celui par défaut, ajoutez l'ID du projet en respectant le format suivant : `project-id`.`region-region-name`.INFORMATION_SCHEMA.view. Exemple : `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT

Pour exécuter la requête :

Console

  1. Dans Cloud Console, ouvrez l'interface utilisateur Web de BigQuery.

    Accéder à Cloud Console

  2. Dans la zone Éditeur de requête, saisissez la requête en SQL standard suivante. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans 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. Cliquez sur Exécuter.

gcloud

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'option --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez :

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

Exemple 2

Dans l'exemple suivant, on récupère l'historique des modifications pour une réservation donnée. Utilisez ces informations pour afficher la liste des modifications apportées à une réservation spécifique.

Pour exécuter la requête sur un projet autre que celui par défaut, ajoutez l'ID du projet en respectant le format suivant : `project-id`.`region-region-name`.INFORMATION_SCHEMA.view. Exemple : `reservation-admin-project`.`region-us`.INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT

Pour exécuter la requête :

Console

  1. Dans Cloud Console, ouvrez l'interface utilisateur Web de BigQuery.

    Accéder à Cloud Console

  2. Dans la zone Éditeur de requête, saisissez la requête en SQL standard suivante. INFORMATION_SCHEMA requiert la syntaxe SQL standard. Le langage SQL standard est la syntaxe par défaut dans Cloud Console.

    SELECT
      *
    FROM
      `reservation-admin-project.region-us`.
      INFORMATION_SCHEMA.RESERVATION_CHANGES_BY_PROJECT
    WHERE
      reservation_name = "..."
    ORDER BY
      change_timestamp DESC;
    
  3. Cliquez sur Exécuter.

gcloud

Exécutez la commande query, puis spécifiez la syntaxe SQL standard à l'aide de l'option --nouse_legacy_sql ou --use_legacy_sql=false. La syntaxe SQL standard est requise pour les requêtes INFORMATION_SCHEMA.

Pour exécuter la requête, saisissez :

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

Étapes suivantes