Tag datasets

This page describes how to use tags to conditionally apply Identity and Access Management (IAM) policies to BigQuery datasets.

A tag is a key-value pair that you can attach directly to a dataset, or that a dataset can inherit from other Google Cloud resources. You can conditionally apply policies based on whether a resource has a specific tag. For example, you might conditionally grant the BigQuery Data Viewer role to a principal on any dataset with the environment:dev tag.

For more information about using tags across the Google Cloud resource hierarchy, see Tags overview.

Required permissions

To use tags in BigQuery, you need the following permissions:

  • To attach a tag to a dataset, you need the bigquery.datasets.createTagBinding IAM permission on the dataset, and the resourcemanager.tagValueBindings.create permission at the organization level on the tag value that you want to attach.
  • To remove a tag from a dataset, you need the bigquery.datasets.deleteTagBinding IAM permission on the dataset, and the resourcemanager.tagValueBindings.delete permission at the organization level on the tag value that you want to delete.
  • To list the tags attached to a dataset, you need the bigquery.datasets.listTagBindings IAM permission.

Both of the following predefined IAM roles include all of the necessary BigQuery permissions:

  • BigQuery Data Owner (roles/bigquery.dataOwner)
  • BigQuery Admin (roles/bigquery.admin)

The Resource Manager permissions are included in the Tag User role (roles/resourcemanager.tagUser).

Create tag keys and values

Before you can attach a tag, you need to create a tag and configure its value. To create tag keys and tag values, refer to Creating a tag and Adding tag values.

Attach tags to a dataset

After you create a tag, you can attach it to a dataset. You can attach only one tag value to a dataset for any given tag key.

To attach a tag to a dataset using the command line, create a tag binding resource by using the gcloud alpha resource-manager tags bindings create command:

gcloud alpha resource-manager tags bindings create \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Replace the following:

  • TAGVALUE_NAME: the permanent ID or namespaced name of the tag value to be attached, such as tagValues/4567890123 or 1234567/my_tag_key/my_tag_value
  • RESOURCE_ID: the full ID of the dataset, including the API domain name (//bigquery.googleapis.com/) to identify the type of resource—for example, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
  • LOCATION: the location of your dataset

List tags attached to a dataset

The following steps provide a list of tag bindings attached directly to a dataset. They do not return any tags that are inherited from parent resources.

Console

  1. Go to the BigQuery page.

    Go to BigQuery

  2. In the Explorer panel, expand your project and select a dataset.

    The tags appear in the Dataset info panel.

gcloud

To get a list of tag bindings attached to a resource, use the gcloud alpha resource-manager tags bindings list command:

gcloud alpha resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

Replace the following:

  • RESOURCE_ID: the full ID of the dataset, including the API domain name (//bigquery.googleapis.com/) to identify the type of resource—for example, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset

  • LOCATION: the location of your dataset

The output is similar to the following:

name: tagBindings/%2F%2Fbigquery.googleapis.com%2Fprojects%2Fmy_project%2Fdatasets%2Fmy_dataset/tagValues/4567890123
parent: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
tagValue: tagValues/4567890123

Detach tags from a dataset

You can detach a tag from a resource by deleting the tag binding resource. If you need to delete a tag, you should first detach the tag.

To detach a tag from a dataset using the command line, delete the tag binding by using the gcloud alpha resource-manager tags bindings delete command:

gcloud alpha resource-manager tags bindings delete \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

Replace the following:

  • TAGVALUE_NAME: the permanent ID or namespaced name of the tag value to be attached, such as tagValues/4567890123 or 1234567/my_tag_key/my_tag_value
  • RESOURCE_ID: the full ID of the dataset, including the API domain name (//bigquery.googleapis.com/) to identify the type of resource—for example, //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
  • LOCATION: the location of your dataset

Delete tags

You should delete all existing tag binding resources before deleting the tag key or value itself. To delete tag keys and tag values, see Deleting tags.

Example

Suppose you are an administrator of an organization. Your data analysts are all members of the group analysts@example.com, which has the BigQuery Data Viewer IAM role on the project userData. A data analyst intern is hired, and according to the company policy they should only have permission to view the anonymousData dataset in the userData project. You can control their access using tags.

  1. Create a tag with the key employee_type and the value intern:

    Example of creating tag key and values.

  2. In the console, go to the IAM page.

    Go to IAM

  3. Locate the row that contains the intern whose dataset access you want to restrict, and click Edit principal in that row.

  4. From the Role menu, select BigQuery Dataset Viewer.

  5. Click Add condition.

  6. In the Title and Description fields, enter values that describe the IAM condition that you want to create.

  7. On the Condition builder tab, click Add.

  8. In the Condition type menu, select Resource, and then select Tag.

  9. In the Operator menu, select has value.

  10. In the Value path field, enter the tag value path in the form ORGANIZATION/TAG_KEY/TAG_VALUE —for example, example.org/employee_type/intern.

    Example of an IAM condition using tags.

    This IAM condition restricts the intern's access to datasets that have the intern tag.

  11. To save the condition, click Save.

  12. To save all changes that you made in the Edit permissions pane, click Save.

  13. To attach the intern tag value to the anonymousData dataset, use the command line to run the gcloud alpha resource-manager tags bindings create command:

    gcloud alpha resource-manager tags bindings create \
--tag-value=tagValues/4567890123 \
--parent=//bigquery.googleapis.com/projects/userData/datasets/anonymousData \
--location=US

Limitations

  • If you delete a tag value, BigQuery does not automatically delete tag bindings that use that value. The tag value ID is required to delete a tag binding after the tag value is deleted. If you do not know the tag value ID, then the only way to remove the binding is to delete the entire dataset.

  • You can attach a maximum of 10 tags to a dataset.

What's next