Data Catalog is deprecated and will be discontinued on June 1, 2026. For steps to transition your Data Catalog users, workloads, and content to Knowledge Catalog (formerly Dataplex Universal Catalog), see Transition from Data Catalog to Knowledge Catalog.

Tag a BigQuery table by using Data Catalog

This quickstart helps you complete the following tasks:

Create a BigQuery dataset and table.
Create a tag template with a schema that defines five tag fields of distinct types. These are string, double, boolean, enumerated, and richtext.
Lookup the Data Catalog entry for your table.
In the Google Cloud console, create business metadata for your entry that includes an overview, data steward, and a tag.

Data Catalog lets you search and tag entries such as BigQuery tables with metadata. Some examples of metadata that you can use for tagging include public and private tags, data stewards, and rich text overview.

Before you begin

Set up your project.

Add a public data entry to your project

Data Catalog entries include data resources such as a BigQuery dataset or a Pub/Sub topic.

Add a public dataset to your project.
1. In Google Cloud console, go to the BigQuery page.
  
  Go to BigQuery
2. In the Explorer section, click Add data and select Public datasets from the list.
3. In the Marketplace panel, search for New York taxi trips and click the relevant search result.
4. Click View Dataset.

Create a dataset and a table

Create a dataset.
1. In the Google Cloud console, open the BigQuery page.
  
  Go to BigQuery
2. In the Explorer panel, select the project where you want to create the dataset.
3. Click the Actions icon and click Create dataset.
4. In the Create dataset page, fill in the following details:
  - For Dataset ID, enter demo_dataset.
  - For Data location, select us (multiple regions in United States).
  - Enable table expiration and specify the number of days.
  - For Encryption, leave the Google-managed encryption key option selected.
  - Click Create dataset.
    
    Note: You cannot add a description or a label when you create a dataset using the Google Cloud console. After the dataset is created, you can add a description, and you can add a label.
Copy a publicly accessible table to demo_dataset.
1. In the Google Cloud console, open the BigQuery page.
  
  Go to BigQuery
2. In the Explorer pane, search for tlc_yellow_trips tables (click Broaden search to all projects if required) and select one of them, such as tlc_yellow_trips_2017. Then click Copy.
3. In the Copy table pane, fill in the following information:
  1. In the Project name drop-down list, select your project.
  2. In the Dataset name drop-down list, select demo_dataset.
  3. For the Table name, enter trips, then click Copy.
4. In the Explorer pane, confirm that the trips table is listed in demo_dataset.

You add Data Catalog tags to the table in the next section.

Create a public tag template and attach a tag for your entry

You must be the dataset owner to attach a tag to a table in the dataset. For more information about public and private tags, see Public and private tags.

In a tag template, tag fields are optional. You don't have to provide a value for a field when attaching a tag to a Data Catalog entry. However, if a template defines a field as required, you must provide a value for the field. If the value is not provided, an error is generated.

You can use lower case letters and underscores to define field names. The tag template fields created in this example are demo fields and aren't auto-updated or synced with BigQuery.

Console

Go to the Knowledge Catalog Tag Templates page.

Go to Tag templates

Click Create tag template and enter the following details:

Enter the Template name as Demo Tag Template.
Retain the default location.
Retain the tag template visibility as Public.

Click Add field to add 5 fields. Use the following table and keep Field description empty.

Field display name	Field ID	Required field	Type
Source of data asset	source	Yes	String
Rows in the asset	num_rows	No	Double
Has PII	has_pii	No	Boolean
PII type	pii_type	No	Enumerated Add values `EMAIL_ADDRESS`, `US_SOCIAL_SECURITY_NUMBER`, and `NONE`.
Context	context	No	Richtext

Click Create.

The Template details page lists all the information about the tag template.
To attach a tag to demo_dataset, go to the Knowledge Catalog Search page.

Go to Search
For Choose search platform, select Data Catalog as the search mode.
In the search box, enter demo_dataset. In the search result, you see the demo_dataset dataset and the trips table.
Click the trips table. A BigQuery table details page opens.
Click Attach tags.
In the Attach tags panel, enter the following details:
1. Select the target as trips.
2. Select the tag template as Demo Tag Template.
3. For tag values, enter the following details:
  - Source of data asset: Copied from tlc_yellow_trips_2017
  - Number of rows in the data asset: 113496874
  - Has PII: FALSE
  - PII type: NONE
4. Click Save.
  
  The tag fields are now listed in the Tags section in the BigQuery table details.

gcloud

Run the gcloud data-catalog tag-templates create command shown below to create a tag template with the following five tag fields:

display_name: Source of data asset
id: source
required: TRUE
type: String
display_name: Number of rows in the data asset
id: num_rows
required: FALSE
type: Double
display_name: Has PII
id: has_pii
required: FALSE
type: Boolean
display_name: PII type
id: pii_type
required: FALSE
type: Enumerated
values:
1. EMAIL_ADDRESS
2. US_SOCIAL_SECURITY_NUMBER
3. NONE


# -------------------------------
# Create a Tag Template.
# -------------------------------

gcloud data-catalog tag-templates create demo_template \
    --location=us-central1 \
    --display-name="Demo Tag Template" \
    --field=id=source,display-name="Source of data asset",type=string,required=TRUE \
    --field=id=num_rows,display-name="Number of rows in the data asset",type=double \
    --field=id=has_pii,display-name="Has PII",type=bool \
    --field=id=pii_type,display-name="PII type",type='enum(EMAIL_ADDRESS|US_SOCIAL_SECURITY_NUMBER|NONE)'

# -------------------------------
# Lookup the Data Catalog entry for the table.
# -------------------------------

ENTRY_NAME=$(gcloud data-catalog entries lookup '//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET/tables/TABLE' --format="value(name)")

# -------------------------------
# Attach a Tag to the table.
# -------------------------------

# Create the Tag file.
cat > tag_file.json << EOF
  {
    "source": "BigQuery",
    "num_rows": 1000,
    "has_pii": true,
    "pii_type": "EMAIL_ADDRESS"
  }
EOF

gcloud data-catalog tags create --entry=${ENTRY_NAME} \
    --tag-template=demo_template --tag-template-location=us-central1 --tag-file=tag_file.json

The location parameter specifies the Compute Engine resource region. Currently, Data Catalog supports only the us-central1 region.

Go

Before trying this sample, follow the Go setup instructions in the Data Catalog quickstart using client libraries. For more information, see the Data Catalog Go API reference documentation.

To authenticate to Data Catalog, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


// The datacatalog_quickstart application demonstrates how to define a tag
// template, populate values in the template, and attach a tag based on the
// template to a BigQuery table.
package main

import (
	"context"
	"flag"
	"fmt"
	"log"
	"strings"
	"time"

	datacatalog "cloud.google.com/go/datacatalog/apiv1"
	"cloud.google.com/go/datacatalog/apiv1/datacatalogpb"
	"github.com/googleapis/gax-go/v2"
)

func main() {
	projectID := flag.String("project_id", "", "Cloud Project ID, used for session creation.")
	location := flag.String("location", "us-central1", "data catalog region to use for the quickstart")
	table := flag.String("table", "myproject.mydataset.mytable", "bigquery table to tag in project.dataset.table format")

	flag.Parse()

	ctx := context.Background()
	client, err := datacatalog.NewClient(ctx)
	if err != nil {
		log.Fatalf("datacatalog.NewClient: %v", err)
	}
	defer client.Close()

	// Create the tag template.
	tmpl, err := createQuickstartTagTemplate(ctx, client, *projectID, *location)
	if err != nil {
		log.Fatalf("createQuickstartTagTemplate: %v", err)
	}
	fmt.Printf("Created tag template: %s\n", tmpl.GetName())

	// Convert a BigQuery resource identifier into the equivalent datacatalog
	// format.
	resource, err := convertBigQueryResourceRepresentation(*table)
	if err != nil {
		log.Fatalf("couldn't parse --table flag (%s): %v", *table, err)
	}

	// Lookup the entry metadata for the BQ table resource.
	entry, err := LookupEntry(ctx, client, &datacatalogpb.LookupEntryRequest{
		TargetName: &datacatalogpb.LookupEntryRequest_LinkedResource{
			LinkedResource: resource,
		},
	})
	if