Créer des requêtes enregistrées

Ce document explique comment créer des requêtes enregistrées et des requêtes enregistrées classiques.

Saved queries

Utilisez les sections suivantes pour apprendre à créer des requêtes enregistrées. Les requêtes enregistrées sont des éléments de code BigQuery Studio fournis par Dataform.

Pour en savoir plus sur la suppression des requêtes enregistrées et la gestion de leur historique, consultez la page Requêtes enregistrées.

Activer BigQuery Studio

Suivez les instructions de la page Activer BigQuery Studio pour la gestion des éléments pour enregistrer, partager et gérer des versions d'éléments de code telles que les requêtes enregistrées.

Important : En mars 2024, les API compatibles avec les fonctionnalités de BigQuery Studio seront automatiquement activées pour tous les projets BigQuery. Pour en savoir plus, consultez la section Activation automatique des API BigQuery Studio.

Autorisations requises

Définissez les autorisations appropriées pour créer, modifier ou afficher des requêtes enregistrées.

Tous les utilisateurs disposant du rôle Administrateur Dataform (roles/dataform.admin) disposent d'un accès propriétaire à toutes les requêtes enregistrées créées dans le projet.

Pour en savoir plus sur la gestion de l'authentification et des accès (IAM) dans BigQuery, consultez la page Contrôle des accès avec IAM.

Autorisations de créer des requêtes enregistrées

Pour créer et exécuter des requêtes enregistrées, vous avez besoin des autorisations IAM suivantes :

• dataform.locations.get
• dataform.locations.list
• dataform.repositories.list

• dataform.repositories.create

  Remarque : Les utilisateurs disposant de l'autorisation dataform.repositories.create peuvent exécuter du code à l'aide du compte de service Dataform par défaut et de toutes les autorisations accordées à ce compte de service. Pour en savoir plus, consultez la section Remarques sur la sécurité pour les autorisations Dataform.

Vous pouvez obtenir ces autorisations à partir des rôles IAM suivants :

• Utilisateur de job BigQuery (roles/bigquery.jobUser)
• Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser)

• Créateur de code (roles/dataform.codeCreator)

  Remarque : Les utilisateurs auxquels le rôle de créateur de code est attribué dans un projet peuvent lister les noms des composants de code de ce projet à l'aide de l'API ou de l'interface de ligne de commande (CLI) Dataform. Les utilisateurs sans droits d'administrateur qui utilisent BigQuery Studio ne peuvent voir que les composants de code qu'ils ont créés ou qui ont été partagés avec eux.

Autorisations de modifier les requêtes enregistrées

Pour modifier et exécuter des requêtes enregistrées, vous avez besoin des rôles IAM suivants :

• Utilisateur de job BigQuery (roles/bigquery.jobUser)
• Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser)
• Éditeur de code (roles/dataform.codeEditor)

Autorisations d'afficher les requêtes enregistrées

Pour afficher et exécuter des requêtes enregistrées, vous avez besoin des rôles IAM suivants :

• Utilisateur de job BigQuery (roles/bigquery.jobUser)
• Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser)
• Lecteur de code (roles/dataform.codeViewer)

Définir la région par défaut des composants de code

Si c'est la première fois que vous créez un composant de code, définissez leur région par défaut. Vous ne pouvez pas modifier la région d'un composant de code après sa création.

Remarque : Si vous créez une requête enregistrée et choisissez une région par défaut différente de celle que vous avez utilisée pour les composants de code, choisissez par exemple us-west1 si vous avez utilisé us-central1. Cette requête et tous les composants de code que vous créez par la suite utilisent cette nouvelle région par défaut. Les composants de code existants continuent à utiliser la région qui leur a été attribuée lors de leur création.

Créer des requêtes enregistrées

Pour créer une requête enregistrée, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Cliquez sur Saisir une nouvelle requête.

3. Dans l'éditeur de requête, saisissez une requête SQL valide. Par exemple, vous pouvez interroger un ensemble de données public :

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;
   

4. Cliquez sur Enregistrer la requête> Enregistrer la requête.

5. Dans la boîte de dialogue Enregistrer la requête, saisissez le nom de la requête enregistrée.

6. Facultatif : pour modifier la région utilisée par cette requête enregistrée et tous les autres éléments de code à l'avenir, sélectionnez une nouvelle région dans la section Région.

7. Cliquez sur Enregistrer.

Accorder l'accès aux requêtes enregistrées

Pour autoriser d'autres utilisateurs à accéder à une requête enregistrée, ajoutez-les à un rôle IAM approprié.

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Requêtes et, si nécessaire, le dossier Requêtes partagées. Recherchez la requête enregistrée à laquelle vous souhaitez accorder l'accès.

3. Cliquez sur Afficher les actions à côté de la requête enregistrée, puis sur Partager > Gérer les autorisations.

4. Dans le volet Gérer les autorisations, cliquez sur Ajouter un utilisateur/groupe.

5. Dans le champ Nouveaux comptes principaux, saisissez un compte principal.

6. Dans la liste Rôle, sélectionnez l'un des rôles suivants :

   • Propriétaire du code : peut effectuer toute action sur la requête enregistrée, y compris la suppression ou le partage.
   • Éditeur de code : peut modifier la requête.
   • Lecteur de code : peut afficher la requête.
   Remarque : Le compte principal doit également disposer du rôle Utilisateur BigQuery (roles/bigquery.user) pour exécuter la requête enregistrée.

7. Facultatif : Pour afficher la liste complète des rôles et des paramètres de partage avancés, cliquez sur Partage avancé.

8. Cliquez sur Enregistrer.

9. Pour revenir aux informations concernant la requête enregistrée, cliquez sur Fermer.

Partager des requêtes enregistrées

Vous pouvez partager une requête enregistrée avec d'autres utilisateurs en générant et en partageant un lien vers cette requête. Pour que les utilisateurs puissent voir la requête enregistrée que vous partagez, vous devez d'abord leur accorder l'accès à la requête enregistrée.

Pour exécuter une requête partagée, les utilisateurs doivent avoir accès aux données auxquelles la requête accède. Pour en savoir plus, consultez la section Accorder l'accès à un ensemble de données.

Si vous prévoyez de partager une requête enregistrée, envisagez d'y inclure un commentaire décrivant son objectif.

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Requêtes et, si nécessaire, développez le dossier Requêtes partagées. Recherchez la requête enregistrée que vous souhaitez partager.

3. Cliquez sur Afficher les actions à côté de la requête, puis sur Partager > Copier le lien.

4. Partagez le lien avec d'autres utilisateurs.

Ouvrir une version de requête enregistrée en tant que nouvelle requête

Pour ouvrir une version existante d'une requête enregistrée en tant que nouvelle requête, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Requêtes et, si nécessaire, le dossier Requêtes partagées. Sélectionnez une requête enregistrée.

3. Sélectionnez le volet Activité.

4. Cliquez sur Afficher les actions à côté d'une version de requête enregistrée, puis sur Ouvrir en tant que nouvelle requête.

Mettre à jour les requêtes enregistrées

Si vous mettez à jour une requête enregistrée, vous pouvez enregistrer les modifications dans une nouvelle version de la requête.

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet et le dossier Requêtes et, si nécessaire, le dossier Requêtes partagées. Cliquez sur le nom d'une requête enregistrée classique pour l'ouvrir.

3. Modifiez la requête.

4. Pour enregistrer la requête modifiée, cliquez sur Enregistrer la requête > Enregistrer la requête.

   Une nouvelle version de la requête est créée, que vous pouvez consulter dans le volet Activité.

Importer des requêtes enregistrées

Vous pouvez importer une requête SQL locale afin de l'utiliser comme requête enregistrée dans BigQuery Studio. La requête enregistrée importée est également visible sur la page BigQuery de la console Google Cloud.

Pour importer une requête enregistrée, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet, puis effectuez l'une des opérations suivantes :

   • À côté de Requêtes, cliquez sur Afficher les actions > Importer une requête SQL.
   • À côté du nom du projet Google Cloud, cliquez sur Afficher les actions > Importer dans le projet > Requête SQL.

3. Dans la boîte de dialogue Importer SQL, dans le champ SQL, cliquez sur Parcourir, puis sélectionnez la requête que vous souhaitez importer.

4. Facultatif : Dans le champ Nom SQL, modifiez le nom de la requête.

5. Dans le champ Région, sélectionnez la région dans laquelle vous souhaitez importer votre requête enregistrée.

6. Cliquez sur Importer.

Votre requête enregistrée s'affiche dans le volet Explorateur.

Requêtes enregistrées classiques

Obsolète : Les requêtes enregistrées, disponibles dans la version preview de BigQuery Studio, remplaceront complètement les requêtes enregistrées classiques d'ici mars 2025. Pour en savoir plus, consultez la page Abandon des requêtes enregistrées classiques. Pour savoir comment migrer vers des requêtes enregistrées, consultez la page Migrer des requêtes enregistrées classiques.

Consultez les sections suivantes pour apprendre à créer et à mettre à jour des requêtes enregistrées classiques. Pour en savoir plus sur le partage, la migration et la suppression de requêtes enregistrées classiques, consultez la page Requêtes enregistrées classiques.

Remarque : Si vous n'avez pas activé BigQuery Studio, les requêtes enregistrées classiques apparaissent dans le dossier Requêtes enregistrées (NUMBER) du volet Explorateur, et non dans le dossier (Classique) Requêtes.

Autorisations requises pour les requêtes enregistrées classiques

Les autorisations IAM suivantes sont requises pour créer, afficher, mettre à jour ou supprimer des requêtes enregistrées classiques :

• Requêtes enregistrées classiques privées :
  • La création de requêtes enregistrées classiques privées ne nécessite pas d'autorisation particulière. Vous pouvez enregistrer une requête privée dans n'importe quel projet, mais vous seul pouvez afficher, mettre à jour ou supprimer la requête.
• Requêtes enregistrées classiques au niveau du projet :
  • La création d'une requête enregistrée classique au niveau du projet nécessite des autorisations bigquery.savedqueries.create. Le rôle bigquery.admin prédéfini comprend ces autorisations bigquery.savedqueries.create.
  • L'affichage d'une requête enregistrée classique au niveau du projet nécessite les autorisations bigquery.savedqueries.get et bigquery.savedqueries.list. Les rôles bigquery.admin et bigquery.user prédéfinis comprennent ces autorisations bigquery.savedqueries.get et bigquery.savedqueries.list.
  • La mise à jour d'une requête enregistrée classiques au niveau du projet nécessite les autorisations bigquery.savedqueries.update. Le rôle bigquery.admin prédéfini comprend ces autorisations bigquery.savedqueries.update.
  • La suppression d'une requête enregistrée au niveau du projet nécessite les autorisations bigquery.savedqueries.delete. Le rôle bigquery.admin prédéfini comprend ces autorisations bigquery.savedqueries.delete.
• Requêtes enregistrées classiques publiques :
  • La création de requêtes enregistrées classiques publiques ne nécessite pas d'autorisation particulière. Vous pouvez enregistrer une requête enregistrée classique publique dans n'importe quel projet, mais vous seul pouvez mettre à jour ou supprimer la requête. Toute personne disposant du lien peut afficher une requête enregistrée classique publique.

Remarque : Les utilisateurs disposant de l'autorisation dataform.repository.list au niveau du projet peuvent voir toutes les requêtes enregistrées créées dans le projet.

Pour en savoir plus sur les rôles IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Créer des requêtes enregistrées classiques

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Cliquez sur Saisir une nouvelle requête.

3. Dans l'éditeur de requête, saisissez une requête SQL valide. Par exemple, vous pouvez interroger un ensemble de données public :

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;
   

4. Cliquez sur Enregistrer la requête (classique) > Enregistrer la requête (classique).

5. Dans la boîte de dialogue Enregistrer la requête, saisissez un nom pour votre requête. Définissez ensuite la Visibilité sur l'une des options suivantes :

   • Personnelle (modifiable uniquement par vous) pour une requête partagée classique privée.
   • Projet (modifiable par les comptes principaux disposant des autorisations appropriées) pour une requête enregistrée classique au niveau du projet.
   • Publique pour une requête enregistrée classique publique.

6. Cliquez sur Enregistrer.

Partager des requêtes enregistrées classiques

Vous pouvez partager les requêtes enregistrées classiques auxquelles vous avez accordé une visibilité au niveau du projet ou publique. La visibilité au niveau du projet permet aux comptes principaux disposant des autorisations requises d'afficher, de mettre à jour ou de supprimer la requête. La visibilité publique permet à tout utilisateur disposant du lien de la requête de l'afficher, mais pas de la mettre à jour ni de la supprimer.

Vous partagez une requête enregistrée classique avec d'autres utilisateurs en générant un lien vers la requête enregistrée classique et en le partageant.

Pour exécuter une requête partagée classique, les utilisateurs doivent avoir accès aux données auxquelles la requête accède. Pour en savoir plus, consultez la section Accorder l'accès à un ensemble de données.

Si vous prévoyez de partager une requête enregistrée classique, envisagez d'y inclure un commentaire décrivant son objectif.

1. Dans le volet Explorateur, développez votre projet et le dossier Requêtes (classiques), puis recherchez la requête enregistrée classique que vous souhaitez partager.
2. Cliquez sur Afficher les actions à côté de la requête, puis sur Obtenir le lien.
3. Partagez le lien avec les utilisateurs auxquels vous souhaitez accorder l'accès à la requête.

Mettre à jour des requêtes enregistrées classiques

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet, le dossier Requêtes (classiques) et, si nécessaire, le dossier Requêtes du projet.

3. Cliquez sur le nom d'une requête enregistrée classique pour l'ouvrir.

4. Modifiez la requête.

5. Pour enregistrer la requête modifiée, cliquez sur Enregistrer la requête (classique) > Enregistrer la requête (classique).

Étapes suivantes

• Découvrez comment gérer les requêtes enregistrées.