更新标签

本页介绍如何更新 BigQuery 资源上的标签。

准备工作

授予为用户提供执行本文档中的每个任务所需权限的 Identity and Access Management (IAM) 角色。 执行任务所需的权限(如果有)列出在任务的“所需权限”部分中。

更新数据集标签

数据集标签可通过以下方式更新:

  • 使用 Google Cloud 控制台
  • 使用 SQL DDL 语句
  • 使用 bq 命令行工具的 bq update 命令
  • 调用 datasets.patch API 方法
  • 使用客户端库

所需权限

如需更新数据集标签,您需要拥有 bigquery.datasets.update IAM 权限。

以下每个预定义 IAM 角色都包含更新数据集标签所需的权限:

  • roles/bigquery.dataOwner
  • roles/bigquery.admin

此外,如果您拥有 bigquery.datasets.create 权限,则可以更新自己创建的数据集的标签。

如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限

更新数据集标签

如需更新数据集上的标签,请选择以下选项之一:

控制台

  1. 在 Google Cloud 控制台中,选择相应的数据集。

  2. 在数据集详情页面上,点击标签右侧的铅笔图标。

    标签铅笔

  3. 修改标签对话框中执行以下操作:

    • 要应用更多标签,请点击添加标签。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
    • 修改现有键或值以更新标签。
    • 点击更新以保存更改。

SQL

使用 ALTER SCHEMA SET OPTIONS DDL 语句在现有数据集上设置标签。设置标签会覆盖数据集中的所有现有标签。以下示例在数据集 mydataset 上设置单个标签:

  1. 在 Google Cloud 控制台中,转到 BigQuery 页面。

    转到 BigQuery

  2. 在查询编辑器中,输入以下语句:

    ALTER SCHEMA mydataset
    SET OPTIONS (labels = [('sensitivity', 'high')]);

  3. 点击 运行

如需详细了解如何运行查询,请参阅运行交互式查询

bq

要添加其他标签或更新数据集标签,请发出带 set_label 标志的 bq update 命令。重复使用该标志可添加或更新多个标签。

如果数据集属于非默认项目,请按以下格式将相应的项目 ID 添加到数据集:[PROJECT_ID]:[DATASET]

bq update \
--set_label key:value \
project_id:dataset

其中:

  • key:value 与要添加或更新的标签的键值对相对应。如果您指定与现有标签相同的键,则系统会更新现有标签的值。键必须是唯一的。
  • project_id 是项目 ID。
  • dataset 是要更新的数据集。

示例:

要更新 mydatasetdepartment 标签,请输入 bq update 命令并将 department 指定为标签键。例如,要将 department:shipping 标签更新为 department:logistics,请输入以下命令。mydataset 属于 myotherproject,而非默认项目。

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset

输出如下所示。

Dataset 'myotherproject:mydataset' successfully updated.

API

要添加其他标签或更新现有数据集的标签,请调用 datasets.patch 方法,然后为数据集资源添加或更新 labels 属性。

由于 datasets.update 方法会替换整个数据集资源,因此最好使用 datasets.patch 方法。

Go

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addDatasetLabel demonstrates adding label metadata to an existing dataset.
func addDatasetLabel(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	ds := client.Dataset(datasetID)
	meta, err := ds.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.DatasetMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Java 设置说明进行操作。如需了解详情,请参阅 BigQuery Java API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import java.util.HashMap;
import java.util.Map;

// Sample to updates a label on dataset
public class LabelDataset {

  public static void runLabelDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    labelDataset(datasetName);
  }

  public static void labelDataset(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example dataset starts with existing label { color: 'green' }
      Dataset dataset = bigquery.getDataset(datasetName);
      // Add label to dataset
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      dataset.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelDataset() {
  // Updates a label on a dataset.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";

  // Retrieve current dataset metadata.
  const dataset = bigquery.dataset(datasetId);
  const [metadata] = await dataset.getMetadata();

  // Add label to dataset metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await dataset.setMetadata(metadata);

  console.log(`${datasetId} labels:`);
  console.log(apiResponse.labels);
}

Python

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to fetch.
# dataset_id = "your-project.your_dataset"

dataset = client.get_dataset(dataset_id)  # Make an API request.
dataset.labels = {"color": "green"}
dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.

print("Labels added to {}".format(dataset_id))

更新表和视图标签

创建表或视图后,可通过以下方式更新标签:

  • 使用 Google Cloud 控制台
  • 使用 bq 命令行工具的 bq update 命令
  • 调用 tables.patch API 方法
    • 由于视图被视为表资源,因此您可以使用 tables.patch 方法来修改视图和表。
  • 使用客户端库

所需权限

如需更新表或视图标签,您需要拥有 bigquery.tables.update IAM 权限。

以下预定义 IAM 角色都包含更新表或视图标签所需的权限:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin

此外,如果您拥有 bigquery.datasets.create 权限,则可以更新自己创建的数据集中的表和视图标签。

如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限

更新表或视图标签

如需更新表或视图标签,请执行以下操作:

控制台

  1. 在 Google Cloud 控制台中选择表或视图。

  2. 点击详细信息标签页,然后点击标签右侧的铅笔图标。

  3. 修改标签对话框中:

    • 要应用更多标签,请点击添加标签。每个键只能在每个表或视图内使用一次,但您可以在不同数据集内的表或视图中使用同一个键。
    • 修改现有键或值以更新标签。
    • 点击更新以保存更改。

SQL

使用 ALTER TABLE SET OPTIONS DDL 语句在现有表上设置标签,或使用 ALTER VIEW SET OPTIONS DDL 语句 在现有视图上设置标签。设置标签会覆盖表或视图上的所有现有标签。以下示例在表 mytable 上设置两个标签:

  1. 在 Google Cloud 控制台中,转到 BigQuery 页面。

    转到 BigQuery

  2. 在查询编辑器中,输入以下语句:

    ALTER TABLE mydataset.mytable
    SET OPTIONS (
      labels = [('department', 'shipping'), ('cost_center', 'logistics')]);

  3. 点击 运行

如需详细了解如何运行查询,请参阅运行交互式查询

bq

要添加其他标签或更新表或视图标签,请发出带 set_label 标志的 bq update 命令。重复使用该标志可添加或更新多个标签。

如果表或视图属于非默认项目,请按以下格式将相应的项目 ID 添加到数据集:project_id:dataset

bq update \
--set_label key:value \
project_id:dataset.table_or_view

其中:

  • key:value 与要添加或更新的标签的键值对相对应。如果您指定与现有标签相同的键,则系统会更新现有标签的值。键必须是唯一的。
  • project_id 是项目 ID。
  • dataset 是包含您要更新的表或视图的数据集。
  • table_or_view 是要更新的表或视图的名称。

示例:

要更新 mytabledepartment 标签,请输入 bq update 命令并将 department 指定为标签键。例如,要将 department:shipping 标签更新为 mytabledepartment:logistics,请输入以下命令。mytable 属于 myotherproject,而非默认项目。

    bq update \
    --set_label department:logistics \
    myotherproject:mydataset.mytable

输出如下所示:

Table 'myotherproject:mydataset.mytable' successfully updated.

API

如需添加标签或更新现有表或视图的标签,请调用 tables.patch 方法,然后为表资源添加或更新 labels 属性。

由于视图被视为表资源,因此您可以使用 tables.patch 方法来修改视图和表。

由于 tables.update 方法会替换整个数据集资源,因此最好使用 tables.patch 方法。

Go

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// addTableLabel demonstrates adding Label metadata to a BigQuery table.
func addTableLabel(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	tbl := client.Dataset(datasetID).Table(tableID)
	meta, err := tbl.Metadata(ctx)
	if err != nil {
		return err
	}

	update := bigquery.TableMetadataToUpdate{}
	update.SetLabel("color", "green")
	if _, err := tbl.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

Java

此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Java 设置说明进行操作。如需了解详情,请参阅 BigQuery Java API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import java.util.HashMap;
import java.util.Map;

// Sample to adds a label to an existing table
public class LabelTable {

  public static void runLabelTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    labelTable(datasetName, tableName);
  }

  public static void labelTable(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // This example table starts with existing label { color: 'green' }
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));
      // Add label to table
      Map<String, String> labels = new HashMap<>();
      labels.put("color", "green");

      table.toBuilder().setLabels(labels).build().update();
      System.out.println("Label added successfully");
    } catch (BigQueryException e) {
      System.out.println("Label was not added. \n" + e.toString());
    }
  }
}

Node.js

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function labelTable() {
  // Adds a label to an existing table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  // Retrieve current table metadata
  const [metadata] = await table.getMetadata();

  // Add label to table metadata
  metadata.labels = {color: 'green'};
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(`${tableId} labels:`);
  console.log(apiResponse.labels);
}

Python

试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档

如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, dataset_id)
# table_ref = dataset_ref.table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.labels == {}
labels = {"color": "green"}
table.labels = labels

table = client.update_table(table, ["labels"])  # API request

assert table.labels == labels

更新作业标签

目前不支持更新作业标签。要更新作业标签,请使用指定的新标签重新提交作业。

将标签转换为标记

如果一个标签的键为空值,则此标签用作标记。您可以创建一个未设定值的新标签,也可以将现有标签转换为数据集、表或视图上的标记。作业标签无法转换为标记。

如果您要标记资源,但无需采用 key:value 格式,则可以使用标记。例如,如果您的表包含由多个群组(支持、开发等)使用的测试数据,则可为该表添加 test_data 标记作识别之用。

所需权限

如需将标签转换为标记,您需要拥有以下 IAM 权限:

  • bigquery.datasets.update(可让您转换数据集标签)
  • bigquery.tables.update(可让您转换表或视图标签)

以下预定义 IAM 角色都包含转换数据集标签所需的权限:

  • roles/bigquery.dataOwner
  • roles/bigquery.admin

以下预定义 IAM 角色都包含转换表或视图标签所需的权限:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin

此外,如果您拥有 bigquery.datasets.create 权限,则可以更新自己创建的数据集的标签以及这些数据集中的表和视图。

如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限

将标签转换为标记

如需将标签转换为标记,请执行以下操作:

控制台

  1. 在 Google Cloud 控制台中,选择数据集、表或视图。

  2. 对于数据集,系统会自动打开“数据集详情”页面。对于表和视图,请点击详细信息以打开详情页面。

    表详细信息

  3. 在详情页面上,点击标签右侧的铅笔图标。

    标签铅笔

  4. 修改标签对话框中执行以下操作:

    • 删除现有标签的值。
    • 点击更新

bq

要将标签转换为标记,请使用带 set_label 标志的 bq update 命令。指定键,再后接英文冒号,但不指定值。这会将现有标签更新为标记。

bq update \
--set_label key: \
resource_id

其中:

  • key: 是要更新为标记的标签键。
  • resource_id 是有效的数据集、表或视图名称。如果资源属于非默认项目,请按以下格式添加项目 ID:project_id:dataset

示例:

输入以下命令可将 mydataset 的现有 test_data:development 标签更新为标记。mydataset 属于 myotherproject,而非默认项目。

bq update --set_label test_data: myotherproject:mydataset

输出如下所示:

Dataset 'myotherproject:mydataset' successfully updated.

API

如需将现有标签转换为标记,请调用 datasets.patch 方法或 tables.patch 方法,并将数据集资源表资源中的标签值替换为空字符串 ("")。

由于视图被视为表资源,因此您可以使用 tables.patch 方法来修改视图和表。另外,由于 tables.update 方法会替换整个数据集资源,因此最好使用 tables.patch 方法。

后续步骤