Pour vous aider à organiser vos ressources BigQuery, vous pouvez ajouter des libellés à vos ensembles de données, tables et vues. Les libellés sont des paires clé/valeur que vous pouvez associer à une ressource. Lorsque vous créez des ressources BigQuery, l'attribution de libellés est facultative.
Une fois vos ressources libellées, vous pouvez les rechercher grâce aux valeurs associées aux libellés. Vous pouvez par exemple exploiter les libellés pour regrouper des ensembles de données par finalité, par environnement, par service, etc.
Cette page décrit comment utiliser des libellés avec vos ressources BigQuery. Elle vous explique également comment ajouter, mettre à jour et supprimer les libellés d'une ressource.
Que sont les libellés ?
Un libellé est une paire clé/valeur qui vous aide à organiser vos ressources BigQuery sur Google Cloud Platform. Vous pouvez associer un libellé à chaque ressource, puis filtrer les ressources par libellé. Les informations sur les libellés sont transmises au système de facturation afin que vous puissiez consulter le détail des frais apparaissant sur votre facture en fonction des libellés.
Cas d'utilisation courants des libellés
Voici quelques cas d'utilisation courants des libellés :
-
Libellés d'équipe ou de centre de coûts : ajoutez des libellés en fonction de l'équipe ou du centre de coûts pour distinguer les ressources BigQuery appartenant à différentes équipes (par exemple,
team:research
etteam:analytics
). Vous pouvez utiliser ce type de libellés pour la comptabilité analytique ou la budgétisation. -
Libellés de composant : par exemple,
component:redis
,component:frontend
,component:ingest
etcomponent:dashboard
. -
Libellés d'environnement ou de production : par exemple,
environment:production
etenvironment:test
. -
Libellés de propriétaire ou de contact : ajoutez des libellés en fonction du propriétaire ou d'un contact principal pour les ressources BigQuery.
-
Libellés d'état : par exemple,
state:active
,state:readytodelete
etstate:archive
.
Exigences relatives aux libellés
Les libellés appliqués à une ressource doivent répondre aux exigences suivantes :
- Chaque ressource peut posséder plusieurs libellés, jusqu'à un maximum de 64.
- Chaque libellé doit correspondre à une paire clé/valeur.
- Les clés doivent comporter un (1) caractère au minimum et 63 au maximum, et ne peuvent pas être vides. Les valeurs peuvent être vides et comporter 63 caractères au maximum.
- Les clés et les valeurs ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des tirets. Tous les caractères doivent être au format d'encodage UTF-8. Les caractères internationaux sont autorisés.
- La partie clé d'un libellé doit être unique. Cependant, vous pouvez utiliser la même clé avec plusieurs ressources.
- Les clés doivent commencer par une lettre minuscule ou un caractère international.
Créer et mettre à jour des libellés d'ensemble de données
Vous pouvez attribuer un libellé à un ensemble de données BigQuery lors de sa création en utilisant la commande bq mk
de l'outil de ligne de commande ou en appelant la méthode API datasets.insert
.
Pour en savoir plus sur l'ajout d'un libellé lors de la création d'un ensemble de données, consultez la section Créer un ensemble de données.
Vous pouvez ajouter ou mettre à jour un libellé après la création d'un ensemble de données en utilisant l'UI Web de BigQuery, la commande bq update
de l'outil de ligne de commande, ou en appelant la méthode API datasets.patch
.
Autorisations requises
Pour ajouter ou mettre à jour un libellé après la création d'un ensemble de données, vous devez disposer d'un accès OWNER
au niveau de l'ensemble de données, ou détenir au niveau du projet un rôle IAM qui comprend les autorisations bigquery.datasets.update
. Les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.datasets.update
:
En outre, comme le rôle bigquery.user
dispose des autorisations bigquery.datasets.create
, un utilisateur ayant le rôle bigquery.user
peut mettre à jour les ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user
crée un ensemble de données, il bénéficie d'un accès OWNER
à celui-ci.
L'accès OWNER
confère à l'utilisateur un contrôle total sur l'ensemble de données.
Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs au niveau des ensembles de données.
Créer ou mettre à jour un libellé d'ensemble de données
Pour mettre à jour un libellé d'ensemble de données ou en ajouter un après la création de la ressource, procédez comme suit :
UI Web
-
Dans l'UI Web, sélectionnez l'ensemble de données.
-
Sur la page Détails de l'ensemble de données, cliquez sur le bouton Modifier situé à droite du champ Libellés.
-
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Saisissez une clé et une valeur pour ajouter un libellé. Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé. Chaque clé ne peut être utilisée qu'une seule fois par ensemble de données, mais vous pouvez exploiter la même clé pour plusieurs ensembles de données au sein d'un même projet.
- Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
-
Cliquez sur OK.
Ligne de commande
Pour ajouter ou mettre à jour un libellé d'ensemble de données, exécutez la commandebq update
en spécifiant le paramètre set_label
. Répétez le paramètre pour ajouter ou mettre à jour plusieurs libellés.
Si l'ensemble de données se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en utilisant le format suivant : [PROJECT_ID]:[DATASET]
.
bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET]
Où :
[KEY:VALUE]
correspond à la paire clé/valeur d'un libellé que vous souhaitez créer ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.[PROJECT_ID]
est l'ID de votre projet.[DATASET]
est le nom de l'ensemble de données que vous mettez à jour.
Exemples :
Pour ajouter un libellé permettant de surveiller tout un service, saisissez la commande bq update
et spécifiez department
comme clé de libellé. Si vous souhaitez par exemple attribuer le libellé department:shipping
à mydataset
dans votre projet par défaut, saisissez la commande suivante :
bq update --set_label department:shipping mydataset
Pour mettre à jour le libellé department
, saisissez la commande bq update
et spécifiez department
comme clé de libellé. Si vous souhaitez par exemple remplacer le libellé department:shipping
par department:logistics
, saisissez la commande ci-dessous. L'ensemble de données mydataset
se trouve dans myotherproject
, et non dans votre projet par défaut.
bq update --set_label department:logistics myotherproject:mydataset
Pour attribuer plusieurs libellés à un ensemble de données, répétez le paramètre set_label
et spécifiez une clé unique pour chaque libellé. De même, pour supprimer plusieurs libellés associés à un ensemble de données, répétez le paramètre clear_label
et spécifiez une paire clé/valeur pour chaque libellé. Si vous souhaitez par exemple attribuer les libellés department:shipping
et cost_center:logistics
à mydataset
dans votre projet par défaut, saisissez la commande suivante :
bq update --set_label department:shipping --set_label cost_center:logistics mydataset
API
Pour ajouter ou mettre à jour un libellé associé à un ensemble de données existant, appelez la méthode datasets.patch
, et ajoutez ou mettez à jour la propriété labels
de la ressource d'ensemble de données.
Comme la méthode datasets.update
remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode datasets.patch
.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Go.
Java
Cet exemple permet d'envoyer une requête à l'API BigQuery en utilisant la bibliothèque cliente HTTP Google pour Java.Python
Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Créer et mettre à jour des libellés de table et de vue
Vous pouvez attribuer un libellé à une table ou à une vue lors de sa création en utilisant la commande bq mk
dans l'outil de ligne de commande, ou en appelant la méthode API tables.insert
.
Pour en savoir plus sur l'ajout d'un libellé lors de la création d'une table ou d'une vue, consultez les sections Créer une table et Créer une vue.
Vous pouvez ajouter ou mettre à jour un libellé après la création d'une table ou d'une vue en utilisant l'UI Web de BigQuery, la commande bq update
de l'outil de ligne de commande, ou en appelant la méthode API tables.patch
.
Comme les vues sont traitées comme des ressources de table, la méthode tables.patch
permet de modifier à la fois des vues et des tables.
Autorisations requises
Pour créer ou mettre à jour un libellé de table ou de vue, vous devez disposer d'un accès OWNER
au niveau de l'ensemble de données, ou détenir un rôle IAM au niveau du projet qui comprend les autorisations bigquery.tables.update
. Voici les rôles IAM prédéfinis au niveau du projet qui incluent les autorisations bigquery.tables.update
:
En outre, comme le rôle bigquery.user
dispose des autorisations bigquery.datasets.create
, un utilisateur affecté au rôle bigquery.user
peut mettre à jour les tables et les vues des ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user
crée un ensemble de données, il bénéficie d'un accès OWNER
à celui-ci. L'accès OWNER
donne à l'utilisateur un contrôle total sur l'ensemble de données et sur les tables et vues qu'il contient.
Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la section Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs au niveau des ensembles de données.
Créer ou mettre à jour un libellé de table ou de vue
Pour mettre à jour un libellé de table ou de vue, ou en ajouter un après la création de la ressource, procédez comme suit :
UI Web
-
Dans l'UI Web, sélectionnez la table ou la vue.
-
Sur la page des détails, cliquez sur le bouton Modifier situé à droite du champ Libellés. L'exemple ci-dessous vous montre les détails d'une table.
-
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Saisissez une clé et une valeur pour ajouter un libellé. Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé. Chaque clé ne peut être utilisée qu'une seule fois par table ou par vue, mais vous pouvez exploiter la même clé pour plusieurs tables ou vues au sein d'un même projet.
- Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
-
Cliquez sur OK.
Ligne de commande
Pour ajouter ou mettre à jour un libellé de table ou de vue, exécutez la commande bq update
en spécifiant le paramètre set_label
. Répétez le paramètre pour ajouter ou mettre à jour plusieurs libellés.
Si la table ou la vue se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en utilisant le format suivant : [PROJECT_ID]:[DATASET]
.
bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE_OR_VIEW]
Où :
[KEY:VALUE]
correspond à la paire clé/valeur d'un libellé que vous souhaitez créer ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.[PROJECT_ID]
est l'ID de votre projet.[DATASET]
est le nom de l'ensemble de données qui contient la table ou la vue que vous mettez à jour.[TABLE_OR_VIEW]
est le nom de la table ou de la vue que vous mettez à jour.
Exemples :
Pour ajouter un libellé permettant de surveiller tout un service, saisissez la commande bq update
et spécifiez department
comme clé de libellé. Si vous souhaitez par exemple attribuer le libellé department:shipping
à mytable
dans votre projet par défaut, saisissez la commande suivante :
bq update --set_label department:shipping mydataset.mytable
Pour ajouter un libellé permettant de surveiller tout un service, saisissez la commande bq update
et spécifiez department
comme clé de libellé. Si vous souhaitez par exemple attribuer le libellé department:shipping
à myview
dans votre projet par défaut, saisissez la commande suivante :
bq update --set_label department:shipping mydataset.myview
Pour mettre à jour le libellé department
, saisissez la commande bq update
et spécifiez department
comme clé de libellé. Si vous souhaitez par exemple remplacer le libellé department:shipping
par department:logistics
pour la table mytable
, saisissez la commande ci-dessous.
La table mytable
se trouve dans myotherproject
, et non dans votre projet par défaut.
bq update --set_label department:logistics myotherproject:mydataset.mytable
Pour attribuer plusieurs libellés à une table ou à une vue, répétez le paramètre set_label
et spécifiez une clé unique pour chaque libellé. Si vous souhaitez par exemple attribuer les libellés department:shipping
et cost_center:logistics
à mytable
dans votre projet par défaut, saisissez la commande suivante :
bq update --set_label department:shipping --set_label cost_center:logistics mydataset.mytable
API
Pour ajouter ou mettre à jour un libellé associé à une table ou à une vue existante, appelez la méthode tables.patch
et ajoutez ou mettez à jour la propriété labels
de la ressource de table.
Comme les vues sont traitées comme des ressources de table, la méthode tables.patch
permet de modifier à la fois des vues et des tables.
Comme la méthode tables.update
remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode tables.patch
.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Go.
Java
Cet exemple permet d'envoyer une requête à l'API BigQuery en utilisant la bibliothèque cliente HTTP Google pour Java.Python
Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Supprimer des libellés
Vous pouvez supprimer un libellé d'un ensemble de données, d'une table ou d'une vue en utilisant l'UI Web de BigQuery, la commande bq update
de l'outil de ligne de commande, ou en appelant les méthodes API datasets.patch
ou tables.patch
.
Supprimer un libellé d'ensemble de données
Pour supprimer un libellé associé à un ensemble de données, vous pouvez utiliser l'UI Web de BigQuery, la commande bq update
de l'outil de ligne de commande ou bien appeler la méthode API datasets.patch
.
Autorisations requises
Pour supprimer un libellé d'ensemble de données, vous devez disposer d'un accès OWNER
au niveau de l'ensemble de données, ou détenir au niveau du projet un rôle IAM qui comprend les autorisations bigquery.datasets.update
. Les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.datasets.update
:
En outre, comme le rôle bigquery.user
dispose des autorisations bigquery.datasets.create
, un utilisateur ayant le rôle bigquery.user
peut mettre à jour les ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user
crée un ensemble de données, il bénéficie d'un accès OWNER
à celui-ci.
L'accès OWNER
confère à l'utilisateur un contrôle total sur l'ensemble de données.
Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs au niveau des ensembles de données.
Supprimer un libellé d'ensemble de données
Pour supprimer un libellé associé à un ensemble de données, procédez comme suit :
UI Web
Dans l'UI Web, sélectionnez l'ensemble de données.
Sur la page Détails de l'ensemble de données, cliquez sur le bouton Modifier situé à droite du champ Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Cliquez sur l'icône de suppression (X) à côté de chaque libellé que vous souhaitez supprimer.
Cliquez sur OK.
Ligne de commande
Pour ajouter ou mettre à jour un libellé d'ensemble de données, exécutez la commande bq update
en spécifiant le paramètre clear_label
. Répétez le paramètre pour supprimer plusieurs libellés.
Si l'ensemble de données se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en utilisant le format suivant : [PROJECT_ID]:[DATASET]
.
bq update --clear_label [KEY] [PROJECT_ID]:[DATASET]
Où :
[KEY]
est la clé d'un libellé que vous souhaitez supprimer.[PROJECT_ID]
est l'ID de votre projet.[DATASET]
est le nom de l'ensemble de données que vous mettez à jour.
Exemples :
Pour supprimer le libellé department:shipping
de mydataset
, saisissez la commande bq update
en spécifiant le paramètre --clear_label
. L'ensemble de données mydataset
se trouve dans votre projet par défaut.
bq update --clear_label department mydataset
Pour supprimer le libellé department:shipping
de mydataset
dans le projet myotherproject
, saisissez la commande bq update
en spécifiant le paramètre --clear_label
.
bq update --clear_label department myotherproject:mydataset
Pour supprimer plusieurs libellés d'un ensemble de données, répétez le paramètre clear_label
et spécifiez la clé de chaque libellé. Si vous souhaitez par exemple supprimer les libellés department:shipping
et cost_center:logistics
de l'ensemble de données mydataset
dans votre projet par défaut, saisissez la commande suivante :
bq update --clear_label department --clear_label cost_center mydataset
API
Pour supprimer un libellé spécifique d'un ensemble de données existant, appelez la méthode datasets.patch
et mettez à jour la propriété labels
de la ressource d'ensemble de données en définissant la valeur de clé du libellé sur null
.
Pour supprimer tous les libellés d'un ensemble de données, appelez la méthode datasets.patch
et supprimez la propriété labels
.
Comme la méthode datasets.update
remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode datasets.patch
.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Go.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Supprimer un libellé de table ou de vue
Pour supprimer un libellé de table ou de vue, vous pouvez utiliser l'UI Web de BigQuery, la commande bq update
de l'outil de ligne de commande, ou bien appeler la méthode API tables.patch
.
Comme les vues sont traitées comme des ressources de table, la méthode tables.patch
permet de modifier à la fois des vues et des tables.
Autorisations requises
Pour supprimer un libellé de table ou de vue, vous devez disposer d'un accès OWNER
au niveau de l'ensemble de données, ou détenir au niveau du projet un rôle IAM qui comprend les autorisations bigquery.tables.update
. Voici les rôles IAM prédéfinis au niveau du projet qui incluent les autorisations bigquery.tables.update
:
En outre, comme le rôle bigquery.user
dispose des autorisations bigquery.datasets.create
, un utilisateur affecté au rôle bigquery.user
peut mettre à jour les tables et les vues des ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user
crée un ensemble de données, il bénéficie d'un accès OWNER
à celui-ci.
L'accès OWNER
à un ensemble de données confère à l'utilisateur un contrôle total sur celui-ci, et sur toutes les tables et les vues qu'il contient.
Pour en savoir plus sur les autorisations et les rôles IAM dans BigQuery, consultez la page Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs au niveau des ensembles de données.
Supprimer un libellé de table ou de vue
Pour supprimer un libellé associé à une table ou à une vue, procédez comme suit :
UI Web
Dans l'UI Web, sélectionnez la table ou la vue.
Sur la page Détails, cliquez sur le bouton Modifier situé à droite du champ Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Cliquez sur l'icône de suppression (X) à côté de chaque libellé que vous souhaitez supprimer.
Cliquez sur OK.
Ligne de commande
Pour supprimer un libellé de table ou de vue, exécutez la commande bq update
en spécifiant le paramètre clear_label
. Répétez le paramètre pour supprimer plusieurs libellés.
Si la table ou la vue se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet au nom de l'ensemble de données en utilisant le format suivant : [PROJECT_ID]:[DATASET]
.
bq update --clear_label [KEY] [PROJECT_ID]:[TABLE_OR_VIEW]
Où :
[KEY]
est la clé d'un libellé que vous souhaitez supprimer.[PROJECT_ID]
est l'ID de votre projet.[DATASET]
est le nom de l'ensemble de données que vous mettez à jour.[TABLE_OR_VIEW]
est le nom de la table ou de la vue que vous mettez à jour.
Exemples :
Pour supprimer le libellé department:shipping
de mydataset.mytable
, saisissez la commande bq update
en spécifiant le paramètre --clear_label
. L'ensemble de données mydataset
se trouve dans votre projet par défaut.
bq update --clear_label department mydataset.mytable
Pour supprimer le libellé department:shipping
de mydataset.myview
dans le projet myotherproject
, saisissez la commande bq update
en spécifiant le paramètre --clear_label
.
bq update --clear_label department myotherproject:mydataset.myview
Pour supprimer plusieurs libellés d'une table ou d'une vue, répétez le paramètre clear_label
et spécifiez la clé de chaque libellé. Si vous souhaitez par exemple supprimer les libellés department:shipping
et cost_center:logistics
de la table mydataset.mytable
dans votre projet par défaut, saisissez la commande suivante :
bq update --clear_label department --clear_label cost_center mydataset.mytable
API
Pour supprimer un libellé spécifique d'une table ou d'une vue existante, appelez la méthode tables.patch
et mettez à jour la propriété labels
de la ressource de table en définissant la valeur de clé du libellé sur null
.
Pour supprimer tous les libellés d'une table ou d'une vue, appelez la méthode tables.patch
et supprimez la propriété labels
.
Comme les vues sont traitées comme des ressources de table, la méthode tables.patch
permet de modifier à la fois des vues et des tables. En outre, comme la méthode tables.update
remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode tables.patch
.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Go.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Créer un tag
Un libellé qui comporte une clé avec une valeur vide fait office de tag. Vous pouvez créer un libellé sans valeur ou bien transformer un libellé existant en tag.
Les tags peuvent s'avérer utiles lorsque vous attribuez des libellés à une ressource, mais n'avez pas besoin d'utiliser le format clé:valeur. Par exemple, si vous disposez d'une table qui contient des données de test utilisées par plusieurs groupes (assistance, développement, etc.), vous pouvez lui attribuer le tag test_data
pour l'identifier.
Pour créer un tag, procédez comme suit :
UI Web
Dans l'UI Web, sélectionnez la ressource concernée (ensemble de données, table ou vue).
Dans le cas des ensembles de données, la page Détails de l'ensemble de données s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Détails pour ouvrir la page des détails.
Sur la page des détails, cliquez sur le bouton Modifier situé à droite du champ Libellés.
Dans la boîte de dialogue Modifier les libellés, effectuez les opérations suivantes :
- Saisissez une nouvelle clé et laissez la valeur vide, ou supprimez la valeur d'un libellé existant. Pour attribuer des tags supplémentaires, cliquez sur Ajouter un libellé.
Cliquez sur OK.
Ligne de commande
Exécutez la commande bq update
en incluant le paramètre set_label
. Spécifiez la clé, suivie du caractère deux-points, mais ne renseignez pas la valeur. Cela permet de transformer un libellé existant en tag ou d'ajouter un nouveau tag.
bq update --set_label [KEY]: [RESOURCE_ID]
Où :
[KEY]
est la clé de libellé que vous souhaitez utiliser en tant que tag.[RESOURCE_ID]
est un nom valide d'ensemble de données, de table ou de vue. Si la ressource se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet en utilisant le format suivant :[PROJECT_ID]:[DATASET]
.
Exemples :
Saisissez la commande ci-dessous pour créer un tag test_data
pour mydataset.mytable
. L'ensemble de données mydataset
se trouve dans votre projet par défaut.
bq update --set_label test_data: mydataset
Saisissez la commande ci-dessous pour transformer le libellé existant test_data:development
de mydataset
en tag. L'ensemble de données mydataset
se trouve dans myotherproject
, et non dans votre projet par défaut.
bq update --set_label test_data: myotherproject:mydataset
API
Appelez la méthode datasets.patch
ou tables.patch
et ajoutez des libellés ayant pour valeur une chaîne vide (""
) dans la ressource d'ensemble de données ou la ressource de table.
Vous pouvez transformer des libellés existants en tags en remplaçant leurs valeurs par une chaîne vide.
Comme les vues sont traitées comme des ressources de table, la méthode tables.patch
permet de modifier à la fois des vues et des tables. En outre, comme la méthode tables.update
remplace la ressource d'ensemble de données dans son intégralité, il est préférable d'utiliser la méthode tables.patch
.
Afficher des libellés
Vous pouvez afficher des libellés en utilisant l'UI Web de BigQuery, la commande bq show
de l'outil de ligne de commande, ou en appelant les méthodes API datasets.get
ou tables.get
.
Comme les vues sont traitées comme des ressources de table, la méthode tables.get
vous permet d'obtenir des informations à la fois sur les libellés de vues et de tables.
Autorisations requises
Les autorisations requises pour afficher des libellés dépendent du type de ressource auquel vous accédez.
Autorisations d'ensemble de données
Pour obtenir des informations sur un ensemble de données, vous devez détenir le rôle READER
au niveau de l'ensemble de données, ou un rôle IAM au niveau du projet qui comprenne les autorisations bigquery.datasets.get
. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.datasets.get
, à l'exception de bigquery.jobUser
.
En outre, comme le rôle bigquery.user
dispose des autorisations bigquery.datasets.create
, un utilisateur affecté au rôle bigquery.user
peut obtenir des informations sur les ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user
crée un ensemble de données, il bénéficie d'un accès OWNER
à celui-ci. L'accès OWNER
donne à l'utilisateur un contrôle total sur l'ensemble de données.
Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la section Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs au niveau des ensembles de données.
Autorisations relatives aux tables et aux vues
Pour obtenir des informations sur des tables, vous devez détenir le rôle READER
au niveau de l'ensemble de données, ou un rôle IAM prédéfini au niveau du projet qui comprend les autorisations bigquery.tables.get
. Si vous disposez des autorisations bigquery.tables.get
au niveau du projet, vous pouvez obtenir des informations sur toutes les tables du projet. Tous les rôles IAM prédéfinis au niveau du projet incluent les autorisations bigquery.tables.get
, à l'exception de bigquery.user
et bigquery.jobUser
.
En outre, comme le rôle bigquery.user
dispose des autorisations bigquery.datasets.create
, un utilisateur affecté au rôle bigquery.user
peut obtenir des informations sur les tables et les vues des ensembles de données qu'il crée. Lorsqu'un utilisateur détenant le rôle bigquery.user
crée un ensemble de données, il bénéficie d'un accès OWNER
à celui-ci. L'accès OWNER
à un ensemble de données donne à l'utilisateur un contrôle total sur celui-ci et sur toutes les tables et vues qu'il contient.
Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la section Contrôle des accès. Pour en savoir plus sur les rôles au niveau des ensembles de données, consultez la section Rôles primitifs au niveau des ensembles de données.
Afficher des libellés d'ensemble de données, de table et de vue
Pour afficher les libellés d'une ressource, procédez comme suit :
UI Web
Dans l'UI Web, sélectionnez la ressource concernée (ensemble de données, table ou vue).
Dans le cas des ensembles de données, la page Détails de l'ensemble de données s'ouvre automatiquement. Pour les tables et les vues, cliquez sur Détails pour ouvrir la page des détails. Les informations sur les libellés apparaissent dans la table d'informations de la ressource.
Ligne de commande
Exécutez la commande bq show
en spécifiant l'ID de ressource. Vous pouvez contrôler le format de sortie à l'aide du paramètre --format
. Si la ressource se trouve dans un projet autre que celui par défaut, ajoutez l'ID du projet en utilisant le format suivant : [PROJECT_ID]:[DATASET]
. Pour améliorer la lisibilité de la sortie, vous pouvez définir le paramètre --format
sur pretty
.
bq show --format=pretty [RESOURCE_ID]
Où [RESOURCE_ID]
est un nom valide d'ensemble de données, de table ou de vue.
Exemples :
Saisissez la commande suivante pour afficher les libellés associés à mydataset
dans votre projet par défaut :
bq show --format=pretty mydataset
Saisissez la commande ci-dessous pour afficher les libellés associés à mydataset.mytable
.
L'ensemble de données mydataset
se trouve dans myotherproject
, et non dans votre projet par défaut.
bq show --format=pretty myotherproject:mydataset.mytable
API
Appelez la méthode datasets.get
ou tables.get
. La réponse inclut tous les libellés associés à cette ressource.
Vous pouvez également afficher les libellés de plusieurs ensembles de données grâce à la commande datasets.list
, ou de plusieurs tables et vues grâce à la commande tables.list
.
Comme les vues sont traitées comme des ressources de table, les méthodes tables.get
et tables.list
vous permettent d'obtenir des informations à la fois sur les libellés de vues et de tables.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Go.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Filtrer des ensembles de données à l'aide de libellés
Pour filtrer des ensembles de données grâce aux libellés, créez une spécification de filtre à utiliser dans l'outil de ligne de commande bq
ou dans l'API BigQuery, en respectant la syntaxe suivante :
"field[:value][ field[:value]..."
Où :
field
est exprimé au formatlabels.[KEY]
, où[KEY]
correspond à une clé de libellé.value
est une valeur de libellé facultative.
À l'heure actuelle, vous ne pouvez pas répertorier des tables ou des vues à l'aide d'une spécification de filtre.
Limites
La spécification de filtre présente les limites suivantes :
- Le seul opérateur logique compatible est l'opérateur "AND". Les comparaisons séparées par des espaces sont traitées comme possédant des opérateurs "AND" implicites.
- Le seul champ actuellement disponible pour le filtrage est le champ "labels.key", où "key" correspond à un nom de libellé.
- Le filtre peut comprendre jusqu'à dix expressions.
- Le filtrage est sensible à la casse.
- Vous ne pouvez pas filtrer des tables ou des vues à l'aide d'une spécification de filtre.
- À l'heure actuelle, vous ne pouvez pas filtrer des ensembles de données à l'aide de l'UI Web de BigQuery.
Exemples de spécifications de filtre
Pour répertorier les ensembles de données qui possèdent le libellé department:shipping
, utilisez la spécification de filtre suivante :
labels.department:shipping
Pour répertorier les ensembles de données qui possèdent plusieurs libellés, séparez les paires clé/valeur par un espace. L'espace est traité comme un opérateur logique AND
. Si vous souhaitez par exemple répertorier les ensembles de données qui possèdent les libellés department:shipping
et location:usa
, utilisez la spécification de filtre suivante :
labels.department:shipping labels.location:usa
Plutôt que d'utiliser une paire clé/valeur, vous pouvez créer un filtre ne contenant qu'une clé. La spécification de filtre suivante répertorie tous les ensembles de données possédant le libellé department
, quelle que soit la valeur :
labels.department
Une alternative consiste à utiliser un astérisque pour représenter toutes les valeurs possibles associées à la clé department
:
labels.department:*
Vous pouvez également utiliser des tags dans une spécification de filtre. Si vous souhaitez par exemple répertorier les ensembles de données qui possèdent le libellé department:shipping
et le tag test_data
, utilisez la spécification de filtre suivante :
labels.department:shipping labels.test_data
Générer des listes filtrées
Pour générer une liste filtrée d'ensembles de données, procédez comme suit :
UI Web
À l'heure actuelle, vous ne pouvez pas filtrer des ensembles de données à l'aide de l'UI Web de BigQuery.
Ligne de commande
Exécutez la commande bq ls
en spécifiant le paramètre --filter
. Si vous répertoriez des ensembles de données dans un projet autre que celui par défaut, spécifiez le paramètre --project_id
.
bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]
Où :
[FILTER_SPECIFICATION]
est une spécification de filtre valide. L'outil de ligne de commande renvoie une liste d'ensembles de données répondant aux exigences du filtre.[PROJECT_ID]
est l'ID de votre projet.
Exemples :
Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent le libellé department:shipping
:
bq ls --filter "labels.department:shipping"
Saisissez la commande suivante pour répertorier les ensembles de données de votre projet par défaut qui possèdent le libellé department:shipping
et le tag test_data
:
bq ls --filter "labels.department:shipping labels.test_data"
Saisissez la commande suivante pour répertorier les ensembles de données du projet myotherproject
qui possèdent le libellé department:shipping
:
bq ls --filter "labels.department:shipping" --project_id myotherproject
API
Appelez la méthode API datasets.list
et incluez la spécification de filtre à l'aide de la propriété filter
.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Go.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Étapes suivantes
- Découvrez comment ajouter des libellés ou des tags aux ressources dans la documentation de Compute Engine.
- Découvrez comment utiliser des libellés dans la documentation de Resource Manager.