Tag tables, views, and datasets

This document describes how to use tags to conditionally applyIdentity and Access Management (IAM)policies to BigQuery tables, views, and datasets.

You can also use tags to conditionallydeny accesswith IAM policies to BigQuery tables, views, anddatasets (Preview). For more information,seeDeny policies.

A tag is a key-value pair that you can attach directly to a table, view, ordataset or a key-value pair that a table, view, or dataset caninherit from otherGoogle Cloud resources. You can conditionally apply policies based onwhether a resource has a specific tag. For example, you might conditionallygrant the BigQuery Data Viewer role to a principal on any dataset with theenvironment:dev tag.

For more information about using tags across the Google Cloudresource hierarchy, seeTags overview.

To grant permissions to many related BigQuery resources at thesame time, including resources that don't exist yet, consider usingIAM Conditions.

Limitations

  • Table tags aren't supported on BigQuery Omni tables, tables in hidden datasets, or temporary tables. Dataset tags aren't supported on BigQuery Omni datasets. Additionally, cross-region queries in BigQuery Omni don't use tags during access control checks of tables in other regions.

  • You can attach a maximum of 50 tags to a table or dataset.

  • All tables referenced in a wildcard query must have exactly the same set of tag keys and values.

  • Users with conditional access to a dataset or table cannot modify permissions for that resource through the Google Cloud console. Permission modifications are only supported through the bq tool and the BigQuery API.

  • Some services outside of BigQuery cannot properly verify IAM tag conditions. If the tag condition is positive, meaning that a user is granted a role on a resource only if that resource has a particular tag, then access is denied to the resource regardless of what tags are attached to it. If the tag condition is negative, meaning that a user is granted a role on a resource only if that resourcedoesn't have a particular tag, then the tag condition is not checked.

    For example, Data Catalog cannot verify IAM tag conditions on BigQuery datasets and tables. Suppose there is a conditional IAM policy that gives an intern the BigQuery Data Viewer role on datasets with theemployee_type=intern tag. Since this is a positive tag condition, the intern cannot view datasets by searching in Data Catalog even if those datasets do have theemployee_type=intern tag. If the tag condition was changed to a negative one, so that the intern could only view datasets that didnot have theemployee_type=intern tag, then the check would be skipped entirely and the intern could view the datasets that they couldn't normally access in BigQuery.

    Best practice: Use positive IAM tag conditions rather than negative ones to prevent granting roles unintentionally.

Required roles

You need to grant IAM roles that give users the necessarypermissions to perform each task in thisdocument.

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

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

The Resource Manager permissions for adding and removing tags are included in theTag User role(roles/resourcemanager.tagUser).

Required permissions

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

OperationBigQuery interfaces (API, CLI, console) and TerraformCloud Resource Manager API or gcloud
Attach a tag to a table or view
  • bigquery.tables.createTagBinding permission on the table or view
  • resourcemanager.tagValueBindings.create permission on the tag value
  • bigquery.tables.create permission to attach a tag when creating a table or view
  • bigquery.tables.update permission to attach a tag when updating a table or view
  • bigquery.tables.createTagBinding permission on the table or view
  • resourcemanager.tagValueBindings.create permission on the tag value
Remove a tag from a table or view
  • bigquery.tables.deleteTagBinding permission on the table or view
  • resourcemanager.tagValueBindings.delete permission on the tag value
  • bigquery.tables.update permission to remove a tag when updating a table or view
  • bigquery.tables.deleteTagBinding permission on the table or view
  • resourcemanager.tagValueBindings.delete permission on the tag value
Attach a tag to a dataset
  • bigquery.datasets.createTagBinding permission on the dataset
  • resourcemanager.tagValueBindings.create permission on the tag value
  • bigquery.datasets.create permission to attach a tag when creating a dataset
  • bigquery.datasets.update permission to attach a tag when updating a dataset
  • bigquery.datasets.createTagBinding permission on the dataset
  • resourcemanager.tagValueBindings.create permission on the tag value
Remove a tag from a dataset
  • bigquery.datasets.deleteTagBinding permission on the dataset
  • resourcemanager.tagValueBindings.delete permission on the tag value
  • bigquery.datasets.update permission to remove a tag when updating a dataset
  • bigquery.datasets.deleteTagBinding permission on the dataset
  • resourcemanager.tagValueBindings.delete permission on the tag value

To list tag keys and key values in the Google Cloud console, you need the followingpermissions:

  • To list the tag keys that are associated with a parent organization orproject, you need theresourcemanager.tagKeys.list permission at the tagkey's parent level and theresourcemanager.tagKeys.get permission for eachtag key. To view the list of tag keys in the BigQuery console,click the dataset name and then clickEdit details, or click the table orview name and then clickDetails> Edit details.

  • To list the tag values of keys that are associated with a parent organizationor project, you need theresourcemanager.tagValues.list permission at thetag value parent level and theresourcemanager.tagValues.get permission foreach tag value. To view the list of tag key values in theBigQuery console, click the dataset name and then clickEdit details, or click the table or view nameand then clickDetails> Edit details.

To use tags in Cloud Resource Manager API or gcloud, you need the followingpermissions:

  • To list the tags attached to atable or view with the Cloud Resource Manager API or the gcloud CLI, youneed thebigquery.tables.listTagBindings IAM permission.
  • To list the effective tags fora table or view, you need thebigquery.tables.listEffectiveTagsIAM permission.
  • To list the tags attached to adataset with the Cloud Resource Manager API or the gcloud CLI,you need thebigquery.datasets.listTagBindingsIAM permission.
  • To list the effective tags fora dataset, you need thebigquery.datasets.listEffectiveTagsIAM permission.

Create tag keys and values

You can create a tag before you attach it to a BigQuery resource,or you can create a tag manually when you create the resource using theGoogle Cloud console.

For information about creating tag keys and tag values, seeCreating a tagandAdding tag valuesin the Resource Manager documentation.

Tag datasets

The following sections describe how to attach tags to new and existing datasets,list tags attached to a dataset, and detach tags from a dataset.

Attach tags when you create a new dataset

After you create a tag, you can attach it to a new BigQuerydataset. You can attach only one tag value to a dataset for any given tag key.You can attach a maximum of 50 tags to a dataset.

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

    If you don't see the left pane, clickExpand left pane to open the pane.

  3. In theExplorer pane, select the project where you want to createyour dataset.

  4. ClickView actions>Create dataset.

  5. Enter the information for your new dataset. For more details, seeCreate datasets.

  6. Expand theTags section.

    1. To apply an existing tag, do the following:

      1. Click the drop-down arrow besideSelect scope and chooseCurrent scope—Select current organization orSelectcurrent project.

        Alternatively, clickSelect scope to search for a resourceor to see a list of current resources.

      2. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    2. To manually enter a new tag, do the following:

      1. Click the drop-down arrow besideSelect a scope and chooseManually enter IDs>Organization,Project, orTags.

      2. If you're creating a tag for your project or organization, inthe dialog, enter thePROJECT_ID or theORGANIZATION_ID, andthen clickSave.

      3. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    3. Optional: To add additional tags to the table, clickAdd tag andfollow the previous steps.

  7. ClickCreate dataset.

SQL

Use theCREATE SCHEMA statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    CREATESCHEMAPROJECT_ID.DATASET_IDOPTIONS(tags=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset that you're creating.
    • TAG_KEY_1: thenamespaced key name that you want to set as the first tag on the dataset, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name for the tag's value, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag.
    • TAG_VALUE_2: the short name for the second tag's value.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Use thebq mk --dataset commandwith the--add_tags flag:

bqmk--dataset\--add_tags=TAG\PROJECT_ID:DATASET_ID

Replace the following:

  • TAG: the tag that you are attaching to the newdataset. Multiple tags are separated by commas. For example,556741164180/env:prod,myProject/department:sales. Each tag must have thenamespaced key name and value short name.
  • PROJECT_ID: the ID of the project where you arecreating a dataset.
  • DATASET_ID: the ID of the new dataset.

Terraform

Use thegoogle_bigquery_dataset resource.

Note: To create BigQuery objects using Terraform, you mustenable theCloud Resource Manager API.

To authenticate to BigQuery, set up Application DefaultCredentials. For more information, seeSet up authentication for client libraries.

The following example creates a dataset namedmy_dataset, then attachestags to it by populating theresource_tags field:

# Create tag keys and valuesdata "google_project" "default" {}resource "google_tags_tag_key" "env_tag_key" {  parent     = "projects/${data.google_project.default.project_id}"  short_name = "env2"}resource "google_tags_tag_key" "department_tag_key" {  parent     = "projects/${data.google_project.default.project_id}"  short_name = "department2"}resource "google_tags_tag_value" "env_tag_value" {  parent     = "tagKeys/${google_tags_tag_key.env_tag_key.name}"  short_name = "prod"}resource "google_tags_tag_value" "department_tag_value" {  parent     = "tagKeys/${google_tags_tag_key.department_tag_key.name}"  short_name = "sales"}# Create a datasetresource "google_bigquery_dataset" "default" {  dataset_id                      = "my_dataset"  default_partition_expiration_ms = 2592000000  # 30 days  default_table_expiration_ms     = 31536000000 # 365 days  description                     = "dataset description"  location                        = "US"  max_time_travel_hours           = 96 # 4 days  # Attach tags to the dataset  resource_tags = {    (google_tags_tag_key.env_tag_key.namespaced_name) : google_tags_tag_value.env_tag_value.short_name,    (google_tags_tag_key.department_tag_key.namespaced_name) : google_tags_tag_value.department_tag_value.short_name  }}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

API

Call thedatasets.insert methodand add your tags to theresource_tags field.

Attach tags to an existing dataset

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

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, clickDatasets, and then select a dataset.

  4. In theDataset info section, clickEdit details.

  5. Expand theTags section.

    1. To apply an existing tag, do the following:

      1. Click the drop-down arrow besideSelect scope and chooseCurrent scope—Select current organization orSelectcurrent project.

        Alternatively, clickSelect scope to search for a resourceor to see a list of current resources.

      2. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    2. To manually enter a new tag, do the following:

      1. Click the drop-down arrow besideSelect a scope and chooseManually enter IDs>Organization,Project, orTags.

      2. If you're creating a tag for your project or organization, inthe dialog, enter thePROJECT_ID or theORGANIZATION_ID, andthen clickSave.

      3. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    3. Optional: To add additional tags to the table, clickAdd tag andfollow the previous steps.

  6. ClickSave.

SQL

Use theALTER SCHEMA SET OPTIONS statement.

The following example overwrites all tags for an existing dataset.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    ALTERSCHEMAPROJECT_ID.DATASET_IDSETOPTIONS(tags=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset that contains the table.
    • TABLE_ID: the name of the table you're tagging.
    • TAG_KEY_1: thenamespaced key name that you want to set as the first tag on the table, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name for the tag's value, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag.
    • TAG_VALUE_2: the short name for the second tag's value.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

The following example uses the+= operator to attach tags to a datasetwithout overwriting existing tags. If an existing tag has the same key, thattag is overwritten.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    ALTERSCHEMAPROJECT_ID.DATASET_IDSETOPTIONS(tags+=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset that contains the table.
    • TABLE_ID: the name of the table you're tagging.
    • TAG_KEY_1: thenamespaced key name that you want to set as the first tag on the table, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name for the tag's value, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag.
    • TAG_VALUE_2: the short name for the second tag's value.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Use thebq update commandwith the--add_tags flag:

bqupdate\--add_tags=TAG\PROJECT_ID:DATASET_ID

Replace the following:

  • TAG: the tag that you are attaching to the dataset.Multiple tags are separated by commas. For example,556741164180/env:prod,myProject/department:sales. Each tag must have thenamespaced key name and value short name.
  • PROJECT_ID: the ID of the project where the existingdataset is located.
  • DATASET_ID: the ID of the existing dataset.

gcloud

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

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

Replace the following:

  • TAG_VALUE_NAME: the permanent ID or namespaced name of the tag value to be attached, such astagValues/4567890123 or1234567/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: thelocation of your dataset.

Terraform

Add tags to the dataset'sresource_tags field, and then apply theupdated configuration using thegoogle_bigquery_dataset resource. Formore information, see the Terraform example inAttach tags when you create a new dataset.

API

Call thedatasets.get methodto get the dataset resource, including theresource_tags field. Add yourtags to theresource_tags field and pass the updated dataset resourceback using thedatasets.update method.

List tags attached to a dataset

The following steps provide a list of tag bindings attached directly to adataset. These methods don't return tags that are inherited from parentresources.

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, clickDatasets, and then select a dataset.

    The tags appear in theDataset info section.

bq

To list tags attached to a dataset, use thebq show command.

bq showPROJECT_ID:DATASET_ID

Replace the following:

  • PROJECT_ID: the ID of the project containing yourdataset.
  • DATASET_ID: the ID of the dataset for which youwant to list the tags.

gcloud

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

gcloud 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 identifythe type of resource. For example,//bigquery.googleapis.com/projects/my_project/datasets/my_dataset.

  • LOCATION: thelocationof your dataset.

The output is similar to the following:

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

Terraform

Use theterraform state show command to list the attributes of thedataset, including theresource_tags field. Run this commandin the directory where the dataset's Terraform configuration file has beenrun.

terraform state show google_bigquery_dataset.default

API

Call thedatasets.get methodto get the dataset resource. The dataset resource includes tags attached tothe dataset in theresource_tags field.

Views

Use theINFORMATION_SCHEMA.SCHEMATA_OPTIONS view.

For example, the following query shows all tags attached to all datasetsin a region. This query returns a table with columns includingschema_name(the dataset names),option_name (always'tags'),object_type (alwaysARRAY<STRUCT<STRING, STRING>>), andoption_value,which contains arrays ofSTRUCT objects representing tags associated witheach dataset. For datasets without assigned tags, theoption_value columnreturns an empty array.

SELECT * from region-REGION.INFORMATION_SCHEMA.SCHEMATA_OPTIONSWHERE option_name='tags'

Replace the following:

  • REGION: theregion where your datasets are located.

Detach tags from a dataset

You can detach a tag from a resource by deleting the tag binding resource. Ifyou're deleting a tag, you must detach it from the dataset before you deleteit. For more information, seeDeleting tags.

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, clickDatasets, and then select a dataset.

  4. In theDataset info section, clickEdit details.

  5. In theTags section, clickDelete item next to thetag you want to delete.

  6. ClickSave.

SQL

Use theALTER SCHEMA SET OPTIONS statement.

The following example detaches tags from a dataset using the-= operator. Todetach all tags from a dataset, you can specifytags=NULL ortags=[].

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    ALTERTABLEPROJECT_ID.DATASET_ID.TABLE_IDSETOPTIONS(tags-=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset that contains the table.
    • TABLE_ID: the name of the table that you're detaching the tags from.
    • TAG_KEY_1: thenamespaced key name of the first tag you want to detach, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name of the value for the tag you want to detach, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag you're detaching.
    • TAG_VALUE_2: the short name for the value of the second tag you're detaching.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Use thebq update commandwith the--remove_tags flag:

bqupdate\--remove_tags=REMOVED_TAG\PROJECT_ID:DATASET_ID

Replace the following:

  • REMOVED_TAG: the tag that you are removing fromthe dataset. Multiple tags are separated by commas. Only accepts keyswithout value pairs. For example,556741164180/env,myProject/department.Each tag must have thenamespaced key name.
  • PROJECT_ID: the ID of the project that containsyour dataset.
  • DATASET_ID: the ID of the dataset to detach tagsfrom.

Alternatively, if you want to removeall tags from a dataset, use thebq update commandwith the--clear_all_tags flag:

bqupdate\--clear_all_tagsPROJECT_ID:DATASET_ID

gcloud

To detach a tag from a dataset using the command line, delete the tagbinding by using thegcloud resource-manager tags bindings delete command:

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

Replace the following:

  • TAG_VALUE_NAME: the permanent ID ornamespaced name of the tag value to be detached, such astagValues/4567890123 or1234567/my_tag_key/my_tag_value.
  • RESOURCE_ID: the full ID of the dataset,including the API domain name (//bigquery.googleapis.com/) toidentify the type of resource. For example,//bigquery.googleapis.com/projects/my_project/datasets/my_dataset.
  • LOCATION: thelocationof your dataset.

Terraform

Remove your tags from the dataset'sresource_tags field, and then applythe updated configuration using thegoogle_bigquery_dataset resource.

API

Call thedatasets.get methodto get the dataset resource, including theresource_tags field. Removeyour tags from theresource_tags field and pass the updated datasetresource back using thedatasets.update method.

Tag tables

The following sections describe how to attach tags to new and existing tables,list tags attached to a table, and detach tags from a table.

Attach tags when you create a new table

After you create a tag, you can attach it to a new table. You can attachonly one tag value to a table for any given tag key. You can attach a maximum of50 tags to a table.

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, clickDatasets, andthen select a dataset.

  4. In theDataset info section, clickCreate table.

  5. Enter the information for your new table. For more details, seeCreate and use tables.

  6. Expand theTags section.

    1. To apply an existing tag, do the following:

      1. Click the drop-down arrow besideSelect scope and chooseCurrent scope—Select current organization orSelectcurrent project.

        Alternatively, clickSelect scope to search for a resourceor to see a list of current resources.

      2. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    2. To manually enter a new tag, do the following:

      1. Click the drop-down arrow besideSelect a scope and chooseManually enter IDs>Organization,Project, orTags.

      2. If you're creating a tag for your project or organization, inthe dialog, enter thePROJECT_ID or theORGANIZATION_ID, andthen clickSave.

      3. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    3. Optional: To add additional tags to the table, clickAdd tag andfollow the previous steps.

  7. ClickCreate table.

SQL

Use theCREATE TABLE statement.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    CREATETABLEPROJECT_ID.DATASET_ID.TABLE_IDOPTIONS(tags=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset where you're creating the table.
    • TABLE_ID: the name of the new table.
    • TAG_KEY_1: thenamespaced key name that you want to set as the first tag on the table, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name for the tag's value, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag.
    • TAG_VALUE_2: the short name for the second tag's value.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Use thebq mk --table commandwith the--add_tags flag:

bqmk--table\--schema=SCHEMA\--add_tags=TAG\PROJECT_ID:DATASET_ID.TABLE_ID

Replace the following:

  • SCHEMA: theinline schema definition.
  • TAG: the tag that you are attaching to the newtable. Multiple tags are separated by commas. For example,556741164180/env:prod,myProject/department:sales. Each tag must havethenamespaced key name and value short name.
  • PROJECT_ID: the ID of the project where you arecreating a table.
  • DATASET_ID: the ID of the dataset where you arecreating a table.
  • TABLE_ID: the ID of the new table.

Terraform

Use thegoogle_bigquery_tableresource.

Note: To create BigQuery objects using Terraform, you mustenable theCloud Resource Manager API.

To authenticate to BigQuery, set up Application DefaultCredentials. For more information, seeSet up authentication for client libraries.

The following example creates a table namedmytable, then attachestags to it by populating theresource_tags field:

# Create tag keys and valuesdata "google_project" "default" {}resource "google_tags_tag_key" "env_tag_key" {  parent     = "projects/${data.google_project.default.project_id}"  short_name = "env3"}resource "google_tags_tag_key" "department_tag_key" {  parent     = "projects/${data.google_project.default.project_id}"  short_name = "department3"}resource "google_tags_tag_value" "env_tag_value" {  parent     = "tagKeys/${google_tags_tag_key.env_tag_key.name}"  short_name = "prod"}resource "google_tags_tag_value" "department_tag_value" {  parent     = "tagKeys/${google_tags_tag_key.department_tag_key.name}"  short_name = "sales"}# Create a datasetresource "google_bigquery_dataset" "default" {  dataset_id                      = "MyDataset"  default_partition_expiration_ms = 2592000000  # 30 days  default_table_expiration_ms     = 31536000000 # 365 days  description                     = "dataset description"  location                        = "US"  max_time_travel_hours           = 96 # 4 days}# Create a tableresource "google_bigquery_table" "default" {  dataset_id  = google_bigquery_dataset.default.dataset_id  table_id    = "mytable"  description = "table description"  # Attach tags to the table  resource_tags = {    (google_tags_tag_key.env_tag_key.namespaced_name) : google_tags_tag_value.env_tag_value.short_name,    (google_tags_tag_key.department_tag_key.namespaced_name) : google_tags_tag_value.department_tag_value.short_name  }}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. LaunchCloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (alsocalled aroot module).

  1. InCloud Shell, create a directory and a new file within that directory. The filename must have the.tf extension—for examplemain.tf. In this tutorial, the file is referred to asmain.tf.
    mkdirDIRECTORY && cdDIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly createdmain.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory.
    terraform init

    Optionally, to use the latest Google provider version, include the-upgrade option:

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and enteringyes at the prompt:
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.
Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

API

Call thetables.insert methodwith a definedtable resource.Include the tags in theresource_tags field.

Attach tags to an existing table

After you create a tag, you can attach it to an existing table. You can attachonly one tag value to a table for any given tag key.

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, and then clickDatasets.

  4. ClickOverview> Tables, and then select a table.

  5. Click theDetails tab, and then clickEdit details.

  6. Expand theTags section.

    1. To apply an existing tag, do the following:

      1. Click the drop-down arrow besideSelect scope and chooseCurrent scope—Select current organization orSelectcurrent project.

        Alternatively, clickSelect scope to search for a resourceor to see a list of current resources.

      2. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    2. To manually enter a new tag, do the following:

      1. Click the drop-down arrow besideSelect a scope and chooseManually enter IDs>Organization,Project, orTags.

      2. If you're creating a tag for your project or organization, inthe dialog, enter thePROJECT_ID or theORGANIZATION_ID, andthen clickSave.

      3. ForKey 1 andValue 1, choose the appropriate valuesfrom the lists.

    3. Optional: To add additional tags to the table, clickAdd tag andfollow the previous steps.

  7. ClickSave.

SQL

Use theALTER TABLE SET OPTIONS statement.

The following example overwrites all tags for an existing table.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    ALTERTABLEPROJECT_ID.DATASET_ID.TABLE_IDSETOPTIONS(tags=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset that contains the table.
    • TABLE_ID: the name of the table you're tagging.
    • TAG_KEY_1: thenamespaced key name that you want to set as the first tag on the table, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name for the tag's value, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag.
    • TAG_VALUE_2: the short name for the second tag's value.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

The following example uses the+= operator to attach a tag to a tablewithout overwriting existing tags. If an existing tag has the same key, thattag is overwritten.

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    ALTERTABLEPROJECT_ID.DATASET_ID.TABLE_IDSETOPTIONS(tags+=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset that contains the table.
    • TABLE_ID: the name of the table you're tagging.
    • TAG_KEY_1: thenamespaced key name that you want to set as the first tag on the table, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name for the tag's value, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag.
    • TAG_VALUE_2: the short name for the second tag's value.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

Use thebq update commandwith the--add_tags flag:

bqupdate\--add_tags=TAG\PROJECT_ID:DATASET_ID.TABLE_ID

Replace the following:

  • TAG: the tag that you are attaching to thetable. Multiple tags are separated by commas. For example,556741164180/env:prod,myProject/department:sales. Each tag must havethenamespaced key name and value short name.
  • PROJECT_ID: the ID of the project that containsyour table.
  • DATASET_ID: the ID of the dataset that containsyour table.
  • TABLE_ID: the ID of the table that you areupdating.

gcloud

To attach a tag to a table using the command line, create atag binding resource by using thegcloud resource-manager tags bindings create command:

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

Replace the following:

  • TAG_VALUE_NAME: the permanent ID or namespaced name of the tag value to be attached, such astagValues/4567890123 or1234567/my_tag_key/my_tag_value.
  • RESOURCE_ID: the full ID of the table, 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/tables/my_table
  • LOCATION: thelocation of your table.

Terraform

Add tags to the table'sresource_tags field, and then apply theupdated configuration using thegoogle_bigquery_table resource. Formore information, see the Terraform example inAttach tags when you create a new table.

API

Call thetables.update methodwith a definedtable resource.Include the tags in theresource_tags field.

List tags attached to a table

You can list tags that are attached directly to a table. This processdoesn't list tags that are inherited from parent resources.

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, and then clickDatasets.

  4. ClickOverview> Tables, and then select a table.

    The tags are visible in theDetails tab.

bq

Use thebq show commandand look for thetags column. If there are no tags on the table, thetags column isn't displayed.

bqshow\PROJECT_ID:DATASET_ID.TABLE_ID

Replace the following:

  • PROJECT_ID: the ID of the project that containsyour table.
  • DATASET_ID: the ID of the dataset that containsyour table.
  • TABLE_ID: the ID of your table.

gcloud

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

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

Replace the following:

  • RESOURCE_ID: the full ID of the table,including the API domain name (//bigquery.googleapis.com/) to identifythe type of resource. For example,//bigquery.googleapis.com/projects/my_project/datasets/my_dataset/tables/my_table.

  • LOCATION: thelocationof your dataset.

The output is similar to the following:

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

Terraform

Use theterraform state show command to list the attributes of thetable, including theresource_tags field. Run this commandin the directory where the table's Terraform configuration file has beenrun.

terraform state show google_bigquery_table.default

API

Call thetables.get methodwith a definedtable resource,and look for theresource_tags field.

Views

Use theINFORMATION_SCHEMA.TABLE_OPTIONS view.

For example, the following query shows all tags attached to all tables in adataset. This query returns a table with columns includingschema_name(the dataset name),option_name (always'tags'),object_type (alwaysARRAY<STRUCT<STRING, STRING>>), andoption_value,which contains arrays ofSTRUCT objects representing tags associated witheach dataset. For tables without assigned tags, theoption_value columnreturns an empty array.

SELECT * fromDATASET_ID.INFORMATION_SCHEMA.TABLE_OPTIONSWHERE option_name='tags'

ReplaceDATASET_ID with the ID of the datasetthat contains your table.

Detach tags from a table

You can remove a tag association from a table by deleting the tag binding.If you're deleting a tag, you must detach it from the table before you deleteit. For more information, seeDeleting tags.

Console

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the left pane, clickExplorer:

    Highlighted button for the Explorer pane.

  3. In theExplorer pane, expand your project, and then clickDatasets.

  4. ClickOverview> Tables, and then select a table.

  5. Click theDetails tab, and then clickEdit details.

  6. In theTags section, clickDelete item next to thetag you want to delete.

  7. ClickSave.

SQL

Use theALTER TABLE SET OPTIONS statement.

The following example detaches tags from a table using the-= operator. Todetach all tags from a table, you can specifytags=NULL ortags=[].

  1. In the Google Cloud console, go to theBigQuery page.

    Go to BigQuery

  2. In the query editor, enter the following statement:

    ALTERTABLEPROJECT_ID.DATASET_ID.TABLE_IDSETOPTIONS(tags-=[('TAG_KEY_1','TAG_VALUE_1'),('TAG_KEY_2','TAG_VALUE_2')];)

    Replace the following:

    • PROJECT_ID: your project ID.
    • DATASET_ID: the ID of the dataset that contains the table.
    • TABLE_ID: the name of the table that you're detaching the tags from.
    • TAG_KEY_1: thenamespaced key name of the first tag you want to detach, for example,'my-project/env' or'556741164180/department'.
    • TAG_VALUE_1: theshort name of the value for the tag you want to detach, for example,'prod' or'sales'.
    • TAG_KEY_2: the namespaced key name for the second tag you're detaching.
    • TAG_VALUE_2: the short name for the value of the second tag you're detaching.

  3. ClickRun.

For more information about how to run queries, seeRun an interactive query.

bq

To remove some tags from a table, use thebq update commandwith the--remove_tags flag:

bqupdate\--remove_tags=TAG_KEYS\PROJECT_ID:DATASET_ID.TABLE_ID

Replace the following:

  • TAG_KEYS: the tag keys that you are detachingfrom the table, separated by commas. For example,556741164180/env,myProject/department. Each tag key must have thenamespaced key name.
  • PROJECT_ID: the ID of the project that containsyour table.
  • DATASET_ID: the ID of the dataset that containsyour table.
  • TABLE_ID: the ID of the table that you areupdating.

To remove all tags from a table, use thebq update commandwith the--clear_all_tags flag:

bqupdate\--clear_all_tags\PROJECT_ID:DATASET_ID.TABLE_ID

gcloud

To remove a tag association from a table using the command line, delete thetag binding by using thegcloud resource-manager tags bindings delete command:

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

Replace the following:

  • TAG_VALUE_NAME: the permanent ID ornamespaced name of the tag value to be deleted, such astagValues/4567890123 or1234567/my_tag_key/my_tag_value.
  • RESOURCE_ID: the full ID of the table,including the API domain name (//bigquery.googleapis.com/) to identifythe type of resource. For example,//bigquery.googleapis.com/projects/my_project/datasets/my_dataset/tables/my_table.
  • LOCATION: thelocationof your dataset.

Terraform

Remove your tags from the table'sresource_tags field, and then applythe updated configuration using thegoogle_bigquery_table resource.

API

Call thetables.update methodwith a definedtable resource,and remove the tags in theresource_tags field. To remove all tags, removetheresource_tags field.

Tag other table-like resources

You can similarly tag BigQuery views, materialized views, clones, andsnapshots.

Delete tags

You can't delete a tag if it's referenced by a table, view, or dataset. Youshould detach all existing tag binding resources before deleting the tag keyor value itself. To delete tag keys and tag values, seeDeleting tags.

Example

Suppose you are an administrator of an organization. Yourdata analysts are all members of the group analysts@example.com, which has theBigQuery Data Viewer IAM role on the projectuserData. A dataanalyst intern is hired, and according to the company policy they should onlyhave permission to view theanonymousData dataset in theuserData project.You can control their access using tags.

  1. Create a tagwith the keyemployee_type and the valueintern:

    Example of creating tag key and values.

  2. In the Google Cloud console, go to theIAM page.

    Go to IAM

  3. Locate the row that contains the intern whose dataset access you want torestrict, and clickEdit principal in that row.

  4. From theRole menu, selectBigQuery Data Viewer.

  5. ClickAdd condition.

  6. In theTitle andDescription fields, enter values that describe theIAM tag condition that you want to create.

  7. On theCondition builder tab, clickAdd.

  8. In theCondition type menu, selectResource, then selectTag.

  9. In theOperator menu, selecthas value.

  10. In theValue path field, enter the tag value path in the formORGANIZATION/TAG_KEY/TAG_VALUE.For example,example.org/employee_type/intern.

    Example of an IAM condition using tags.

    This IAM tag condition restricts the intern's access todatasets that have theintern tag.

  11. To save the tag condition, clickSave.

  12. To save any changes that you made in theEdit permissions pane, clickSave.

  13. To attach theintern tag value to theanonymousData dataset, use thecommand line to run thegcloud resource-manager tags bindings createcommand. For example:

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

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.