Créer des requêtes enregistrées

Lorsque vous écrivez du code SQL dans l'éditeur de requête, vous pouvez enregistrer votre requête et la partager avec d'autres utilisateurs. 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 Gérer les requêtes enregistrées.

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 Identity and Access Management (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

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

• Utilisateur de tâche 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.

Remarque : Lorsque vous créez une requête enregistrée, BigQuery vous attribue le rôle Administrateur Dataform (roles/dataform.admin) pour cette requête. Tous les utilisateurs disposant du rôle Administrateur Dataform attribué au Google Cloud projet disposent d'un accès propriétaire à toutes les requêtes enregistrées créées dans le projet. Pour remplacer ce comportement, consultez la section Accorder un rôle spécifique lors de la création d'une ressource.

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 tâche 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 tâche BigQuery (roles/bigquery.jobUser)
• Utilisateur de sessions de lecture BigQuery (roles/bigquery.readSessionUser)
• Lecteur de code (roles/dataform.codeViewer)

Remarques sur la sécurité pour les requêtes enregistrées

Étant donné que les composants de code dans BigQuery sont fournis par Dataform, vous devez tenir compte des implications de sécurité suivantes pour les utilisateurs ayant accès à ces composants :

• La visibilité des composants de code est régie par les autorisations Dataform au niveau du projet. Les utilisateurs disposant de l'autorisation dataform.repositories.list (incluse dans les rôles BigQuery standards tels qu'Utilisateur de tâche BigQuery, Utilisateur BigQuery Studio et Utilisateur BigQuery) peuvent voir tous les composants de code dans le volet Explorateur du Google Cloud projet, qu'ils aient créé ces composants ou qu'ils aient été partagés avec eux. Pour limiter la visibilité, vous pouvez créer des rôles personnalisés qui excluent l'autorisation dataform.repositories.list.
• Tous les codes secrets partagés avec l'agent de service Dataform sont potentiellement accessibles aux utilisateurs qui peuvent modifier ces composants. Pour sécuriser vos identifiants, limitez l'accès en création et en modification aux utilisateurs de confiance, et limitez les codes secrets accessibles à l'agent de service Dataform. Pour en savoir plus, consultez la section Accès aux codes secrets lors de l'installation du package.

Pour en savoir plus, consultez la section Remarques sur la sécurité pour les autorisations Dataform.

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

Tous les nouveaux composants de code de votre Google Cloud projet utilisent une région par défaut. Une fois le composant créé, vous ne pouvez plus modifier sa région.

Important : Si vous modifiez la région lors de la création d’un composant de code, cette région devient la région par défaut pour tous les composants de code suivants. Les composants de code existants ne sont pas concernés.

Pour définir la région par défaut des nouveaux composants de code, procédez comme suit :

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur Fichiers pour ouvrir l'explorateur de fichiers :

   

3. À côté du nom du projet, cliquez sur Afficher les actions du volet Fichiers > Changer de région de code.

4. Sélectionnez la région de code que vous souhaitez utiliser par défaut.

5. Cliquez sur Enregistrer.

Pour obtenir la liste des régions compatibles, consultez la page Emplacements BigQuery Studio.

Chiffrer avec CMEK

Vous pouvez chiffrer vos requêtes enregistrées fournies par Dataform à l'aide de clés de chiffrement gérées par le client (CMEK) en utilisant la clé CMEK par défaut au niveau du projet pour l'API Dataform. Vous ne pouvez pas appliquer de clés CMEK individuelles aux requêtes enregistrées dans la console. Google Cloud Les nouveaux paramètres ne s'appliquent qu'aux requêtes enregistrées nouvellement créées.

Pour en savoir plus et obtenir des instructions sur la définition de la clé par défaut, consultez la section Utiliser CMEK pour protéger les composants de code BigQuery Studio.

Créer des requêtes enregistrées

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

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

   Accéder à BigQuery

2. Cliquez sur Requête SQL.

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;

   Vous pouvez également utiliser le volet Référence pour créer des requêtes.

4. Cliquez sur Enregistrer > Enregistrer la requête ou appuyez sur Ctrl+S (ou Cmd+S sur macOS).

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

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

7. Cliquez sur Enregistrer.

   La première version de la requête enregistrée est créée.

8. Facultatif : Une fois la requête enregistrée, utilisez la barre d'outils suivante pour afficher les détails de la requête ou l'historique des versions, ajouter des commentaires, répondre à un commentaire existant ou obtenir un lien vers celui-ci :

   

   La fonctionnalité de barre d'outils Commentaires est disponible en version bêta. Pour nous faire part de vos commentaires ou demander de l'aide concernant cette fonctionnalité, envoyez un e-mail à [e-mail].

Partager des requêtes enregistrées

Pour partager une requête enregistrée avec un utilisateur, vous devez d'abord lui accorder l'accès à la requête enregistrée et l'ajouter à un rôle IAM approprié. Ensuite, générez un lien vers la requête enregistrée et partagez-le avec l'utilisateur.

Les utilisateurs avec lesquels vous partagez une requête ne voient que la version la plus récente de la requête. Les modifications enregistrées automatiquement que vous n'avez pas explicitement enregistrées n'apparaissent pas dans la requête partagée.

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

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur Fichiers pour ouvrir l'explorateur de fichiers.

   Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

3. Dans le volet Fichiers, développez votre projet et ses sous-dossiers pour trouver la requête enregistrée que vous souhaitez partager.

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

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

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

7. 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.

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

9. Cliquez sur Enregistrer.

10. Pour revenir aux détails de la requête enregistrée, cliquez sur Fermer.

11. Pour générer un lien vers la requête enregistrée, cliquez sur Afficher les actions > Partager > Copier le lien.

    Le lien est copié dans le presse-papiers.

Ouvrir une version d'une 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 Google Cloud console, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur Fichiers pour ouvrir l'explorateur de fichiers :

   

   Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

3. Dans le volet Fichiers, développez votre projet et ses sous-dossiers pour trouver la requête enregistrée que vous souhaitez ouvrir.

4. Cliquez sur la requête enregistrée, puis sur Historique des versions.

5. 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

Les modifications que vous apportez au texte d'une requête enregistrée sont automatiquement enregistrées deux secondes après que vous avez cessé de saisir du texte et apparaissent dans votre Historique des versions sous Vos modifications. Les modifications enregistrées automatiquement ne constituent pas une nouvelle version de la requête. Vos modifications enregistrées automatiquement réapparaissent chaque fois que vous ouvrez la requête, mais ne sont visibles par personne d'autre, sauf si vous les enregistrez explicitement en tant que nouvelle version de la requête. Les requêtes enregistrées automatiquement sont disponibles en version bêta.

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur Fichiers pour ouvrir l'explorateur de fichiers :

   

   Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

3. Dans le volet Fichiers, développez votre projet et ses sous-dossiers pour trouver la requête enregistrée que vous souhaitez mettre à jour.

4. Cliquez sur la requête enregistrée pour l'ouvrir.

5. Modifiez la requête.

6. Pour enregistrer la requête modifiée, cliquez sur Enregistrer la requête > Enregistrer la requête ou appuyez sur Ctrl+S (ou Cmd+S sur macOS).

   Une nouvelle version de la requête est créée.

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 Google Cloud console.

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

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

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur Fichiers pour ouvrir l'explorateur de fichiers :

   

   Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

3. Dans le volet Fichiers, cliquez sur Afficher les actions à côté du dossier dans lequel vous souhaitez importer la requête, puis cliquez sur Importer > Requête.

4. 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.

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

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

7. Cliquez sur Importer.

Vous pouvez accéder à votre requête enregistrée via le volet Fichiers ou le volet Explorateur.

Requêtes enregistrées classiques

Obsolète : Les requêtes enregistrées, disponibles dans BigQuery Studio, remplaceront complètement les requêtes enregistrées classiques à l'avenir. Le calendrier d'abandon est en cours d'examen. 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 pas dans le dossier Requêtes(classiques).

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.

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 Google Cloud console, accédez à la page BigQuery.

   Accéder à BigQuery

2. Cliquez sur Requête SQL.

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 enregistré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'inclure un commentaire dans la requête décrivant son objectif.

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

1. Dans le volet de gauche, cliquez sur Explorateur.

   Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

2. Dans le volet Explorateur, développez votre projet et cliquez sur Requêtes(classiques).

3. Recherchez et cliquez sur la requête enregistrée classique à laquelle vous souhaitez accorder l'accès. Vous pouvez utiliser la fonctionnalité de recherche ou des filtres pour trouver votre requête.

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

5. 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 Google Cloud console, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le volet de gauche, cliquez sur Explorateur:

   

   Si le volet de gauche ne s'affiche pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

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

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

5. Modifiez la requête.

6. 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.