Labeling Datasets

Command-line

Use the bq update command with the set_label flag.

• bq update --set_label [KEY1:VALUE1] --set_label [KEY2:VALUE2] --set_label [KEYN:VALUEN] [DATASET_ID]

Where [KEY1:VALUE1], [KEY2:VALUE2], and [KEYN:VALUEN] are label key:value pairs that you want to create, and [DATASET_ID] is a valid dataset ID.

For example, to add a label to track departments, you can create a label with a department key:

• bq update --set_label department:shipping [DATASET_ID]

API

To create a label using the API, add a labels field to the dataset's configuration object when creating or updating the dataset.

{
  "kind": "bigquery#dataset",
  ...
  "friendlyName": string,
  "description": string,
  "labels": {
    "[KEY1]": "[VALUE1]",
    "[KEY2]": "[VALUE2]"
  }
   ...
}

Where [KEY1] and [KEY2] are label keys, and [VALUE1] and [VALUE2] are the corresponding label values that you want to create.

Command-line

Use the bq update command with the set_label flag.

• bq update --set_label [KEY1:VALUE1] --set_label [KEY2:VALUE2] --set_label [KEYN:VALUEN] [DATASET_ID]

Where [KEY1:VALUE1], [KEY2:VALUE2], and [KEYN:VALUEN] are label key:value pairs that you want to update, and [DATASET_ID] is a valid dataset ID.

For example, to update a label that tracks departments, specify a new value for the department key:

• bq update --set_label department:receiving [DATASET_ID]

API

1. Modify the labels field in the dataset's configuration object.

   {
     "kind": "bigquery#dataset",
     ...
     "friendlyName": string,
     "description": string,
     "labels": {
       "[KEY1]": "[VALUE1]",
       "[KEY2]": "[VALUE2]"
     }
      ...
   }
   

   Where [KEY1] and [KEY2] are label keys, and [VALUE1] and [VALUE2] are the corresponding label values that you want to create.

2. To replace all labels in the dataset, call Datasets.update().

3. Alternately, to replace only the labels specified and otherwise preserve existing ones, call Datasets.patch().

If there are concurrent calls to update() and delete(), BigQuery executes the last one received.

Command-line

Use the bq update command with the clear_label flag.

• bq update --clear_label [KEY1] --clear_label [KEY2] --clear_label [KEYN] [DATASET_ID]

Where [KEY1], [KEY2], and [KEYN] are label keys that you want to delete, and [DATASET_ID] is a valid dataset ID.

For example, to delete a label that tracks departments, specify the department key:

• bq update --clear_label department [DATASET_ID]

API

To remove all labels from a dataset:

1. Remove the labels field from the dataset's configuration object.

   {
     "kind": "bigquery#dataset",
     ...
     "friendlyName": string,
     "description": string,
      ...
   }
   

2. Call Datasets.update().

To delete specific labels from a dataset and otherwise preserve the other existing labels:

1. Change the value of the labels you want to delete to null:

   {
     "kind": "bigquery#dataset",
     ...
     "friendlyName": string,
     "description": string,
     "labels": {
       "[KEY1]": null,
       "[KEY2]": null
     }
      ...
   }
   

   Where [KEY1] and [KEY2] are label keys that you want to delete.

2. Call Datasets.patch().

If there are concurrent calls to update() and delete(), BigQuery executes the last one received.

Command-line

Use the bq update command with the set_label flag. Specify the key, followed by a colon, but leave the value unspecified.

• bq update --set_label [KEY1]: --set_label [KEY2]: --set_label [KEYN]: [DATASET_ID]

Where [KEY1], [KEY2], and [KEYN] are label keys that you want to keep without values, and [DATASET_ID] is a valid dataset ID.

For example, to delete the value associated with the department key, specify the department key with an empty value:

• bq update --set_label department: [DATASET_ID]

API

To delete a label's value, but retain the label's key:

1. Change the value of the labels you want to delete to the empty string (""):

   {
     "kind": "bigquery#dataset",
     ...
     "friendlyName": string,
     "description": string,
     "labels": {
       "[KEY1]": "",
       "[KEY2]": ""
     }
      ...
   }
   

   Where [KEY1] and [KEY2] are label keys that you want to keep, but with no values attached to them.

2. Call Datasets.patch().

If there are concurrent calls to update() and delete(), BigQuery executes the last one received.

Command-line

Use the bq show command with the dataset ID.

• bq show [DATASET_ID]

The command-line tool returns the labels associated with that dataset.

API

Call the Datasets.get() command. The response includes all labels associated with that dataset.

Alternately, you can use Datasets.list() to view the labels for multiple datasets. You can also use filters to return a group of datasets that share common labels.

Command-line

Use the bq ls command with the filter flag where [FILTER_SPECIFICATION] is a valid filter specification and [DATASET_ID] is a valid dataset ID:

• bq ls --filter "[FILTER_SPECIFICATION]" [DATASET_ID]

The command-line tool returns a list of datasets that meet the filter requirements.

For example, the following command returns a list of datasets that have a department key with a value of shipping:

• bq ls --filter "labels.department:shipping" [DATASET_ID]

API

1. Add a filter property that specifies the filter you want to use:

   {
     "kind": "bigquery#dataset",
     ...
     "friendlyName": string,
     "description": string,
     "filter": "[FILTER_SPECIFICATION]",
      ...
   }
   

   Where [FILTER_SPECIFICATION] is a valid filter specification.

2. Call the Datasets.list() command. The response includes all labels associated with that dataset.