添加和使用标签

为了更好地整理您的 BigQuery 资源,您可以为数据集、表和视图添加标签。标签是可以附加到资源的键值对。创建 BigQuery 资源时,并不是必须要添加标签。

为资源添加标签后,可以根据标签值搜索资源。例如,您可以使用标签按照用途、环境、部门等对数据集进行分组。

本页面介绍了如何为 BigQuery 资源添加标签。

如需了解如何管理标签,请参阅管理标签

什么是标签?

标签是一种键值对,可帮助您整理 Google Cloud Platform BigQuery 资源。您可以将标签附加到各项资源,然后根据其标签对资源进行过滤。标签的相关信息会传递到结算系统,因此您可以根据标签来细分结算费用

标签的常见用途

以下是标签的一些常见使用场景:

  • 团队或成本中心标签:根据团队或成本中心添加标签,以区分不同团队所拥有的 BigQuery 资源(例如 team:researchteam:analytics)。您可以在进行成本核算或预算时使用此类标签。

  • 组件标签:例如 component:rediscomponent:frontendcomponent:ingestcomponent:dashboard

  • 环境或阶段标签:例如 environment:productionenvironment:test

  • 状态标签:例如 state:activestate:readytodeletestate:archive

标签要求

应用于资源的标签必须符合以下要求:

  • 每项资源可以有多个标签,但不能超过 64 个。
  • 每个标签都必须采用键值对形式。
  • 键至少包含 1 个字符,最多包含 63 个字符,且不能为空。值可以为空,且最多包含 63 个字符。
  • 键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。
  • 标签的键部分必须是唯一的。不过,您可以将同一个键用于多个资源。
  • 键必须以小写字母或国际字符开头。

添加数据集标签

要在创建 BigQuery 数据集时向其添加标签,您可以使用命令行工具的 bq mk 命令或调用 datasets.insert API 方法。目前,如果通过 GCP Console 或经典版 BigQuery 网页界面创建数据集,您无法在创建时为其添加标签。

本页面介绍如何在创建数据集后向其添加标签。要详细了解如何在创建数据集时添加标签,请参阅创建数据集

向数据集添加标签后,标签会包含在存储空间结算数据中,但您不会在与作业相关的结算数据中看到数据集标签。

所需权限

要向现有数据集添加标签,您必须具有数据集级层的 OWNER 访问权限,或者必须分配有包含 bigquery.datasets.update 权限的项目级层 IAM 角色。以下预定义的项目级层 IAM 角色具有 bigquery.datasets.update 权限:

此外,由于 bigquery.user 角色具有 bigquery.datasets.create 权限,因此被指定为 bigquery.user 角色的用户可以更新该用户创建的任何数据集。在被指定为 bigquery.user 角色的用户创建数据集后,系统将为该用户授予对该数据集的 OWNER 访问权限。 凭借对数据集的 OWNER 访问权限,用户可以完全掌控该数据集。

要详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问权限控制。要详细了解数据集级层角色,请参阅数据集的初始角色

向数据集添加标签

要在创建数据集后向其添加标签,请执行以下操作:

Console

  1. 在 BigQuery 网页界面中,选择数据集。

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

    标签铅笔

  3. 修改标签对话框中:

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

经典版界面

  1. 在 BigQuery 网页界面中,选择数据集。

  2. Dataset Details 页面,点击 Labels 右侧的 Edit

    修改标签

  3. Edit Labels 对话框中:

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

      新标签

命令行

要向现有数据集添加标签,请发出带 set_label 标志的 bq update 命令。重复使用该标志可添加多个标签。

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

    bq update --set_label [KEY:VALUE] [PROJECT_ID]:[DATASET]

其中:

  • [KEY:VALUE] 对应于要添加的标签的键值对。键必须是唯一的。
  • [PROJECT_ID] 是您的项目 ID。
  • [DATASET] 是要为其添加标签的数据集。

示例:

要添加标签来跟踪部门,请输入 bq update 命令并将 department 指定为标签键。例如,要将 department:shipping 标签添加到默认项目中的 mydataset,请输入:

    bq update --set_label department:shipping mydataset

要向某个数据集添加多个标签,请重复使用 set_label 标志并为每个标签指定唯一键。例如,要将 department:shipping 标签和 cost_center:logistics 标签添加到默认项目中的 mydataset,请输入:

    bq update --set_label department:shipping --set_label cost_center:logistics mydataset

API

要向现有数据集添加标签,请调用 datasets.patch 方法并填充数据集资源labels 属性。

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

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。
static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
static final JsonFactory JSON_FACTORY = new JacksonFactory();

public static class Dataset {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Dataset addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a dataset.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelDataset(
    String projectId, String datasetId, String labelKey, String labelValue) throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Dataset dataset = new Dataset();
  dataset.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, dataset);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url = new GenericUrl(String.format(urlFormat, projectId, datasetId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Dataset responseDataset = response.parseAs(Dataset.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseDataset.getLabels().get(labelKey));
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# dataset = client.get_dataset(dataset_ref)  # API request

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

dataset = client.update_dataset(dataset, ["labels"])  # API request

assert dataset.labels == labels

添加表和视图标签

要在创建表或视图时向其添加标签,您可以使用命令行工具的 bq mk 命令或调用 tables.insert API 方法。

本页面介绍如何向现有表或视图添加标签。如需详细了解如何在创建表或视图时添加标签,请参阅创建表创建视图

要在创建表或视图后向其添加标签,您可以使用 GCP Console、经典版 BigQuery 网页界面或命令行工具的 bq update 命令,也可以调用 tables.patch API 方法。由于视图被视为表资源,因此您可以使用 tables.patch 方法修改视图和表。

所需权限

要向现有表或视图添加标签,您必须具有数据集级层的 OWNER 访问权限,或者必须分配有包含 bigquery.tables.update 权限的项目级层 IAM 角色。以下预定义的项目级层 IAM 角色包含 bigquery.tables.update 权限:

此外,由于 bigquery.user 角色具有 bigquery.datasets.create 权限,因此被指定为 bigquery.user 角色的用户可以更新用户创建的任何数据集内的表和视图。在被指定为 bigquery.user 角色的用户创建数据集后,系统将为该用户授予对该数据集的 OWNER 访问权限。凭借对数据集的 OWNER 访问权限,用户可以完全掌控该数据集以及其中的表和视图。

要详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问控制。要详细了解数据集级层角色,请参阅数据集的初始角色

向表或视图添加标签

要向现有表或视图添加标签,请执行以下操作:

Console

  1. 在 BigQuery 网页界面,选择表或视图。

  2. 点击详情标签页。

    表详细信息

  3. 点击标签右侧的铅笔图标。

    标签铅笔

  4. 修改标签对话框中:

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

经典版界面

选项 1:手动修改标签 1. 在 BigQuery 网页界面,选择表或视图。

  1. 在详情页面,点击 Labels 右侧的 Edit。以下示例展示了表的详细信息。

    修改标签

  2. Edit Labels 对话框中:

    • 输入键和值以添加标签。要应用更多标签,请点击 Add Label。每个键只能在每个表或视图内使用一次,但您可以在不同数据集内的表或视图中使用同一个键。
    • 点击 OK

      新标签

选项 2:使用 DDL 语句

借助数据定义语言 (DDL) 语句,您可以使用标准 SQL 查询语法创建并修改表和视图。

详细了解如何使用数据定义语言语句

  1. 点击 Compose query

  2. New Query 文本区域中输入 DDL 语句。

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       labels=[("department", "shipping"), ("cost_center", "logistics")]
     )
     

命令行

要向现有表或视图添加标签,请发出带 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] 是您要为其添加标签的表或视图的名称。

示例:

要添加表标签来跟踪部门,请输入 bq update 命令并将 department 指定为标签键。例如,要将 department:shipping 标签添加到默认项目中的 mytable,请输入:

    bq update --set_label department:shipping mydataset.mytable

要添加视图标签来跟踪部门,请输入 bq update 命令并将 department 指定为标签键。例如,要将 department:shipping 标签添加到默认项目中的 myview,请输入:

    bq update --set_label department:shipping mydataset.myview

要向某个表或视图添加多个标签,请重复使用 set_label 标志并为每个标签指定唯一键。例如,要将 department:shipping 标签和 cost_center:logistics 标签添加到默认项目中的 mytable,请输入:

    bq update --set_label department:shipping --set_label cost_center:logistics mydataset.mytable

API

要向现有表或视图添加标签,请调用 tables.patch 方法并填充表资源labels 属性。

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

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

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

Java

此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。
public static class Table {
  @Key private Map<String, String> labels;

  public Map<String, String> getLabels() {
    return this.labels;
  }

  public Table addLabel(String key, String value) {
    if (this.labels == null) {
      this.labels = new HashMap<>();
    }
    this.labels.put(key, value);
    return this;
  }
}

/**
 * Add or modify a label on a table.
 *
 * <p>See <a href="https://cloud.google.com/bigquery/docs/labeling-datasets">the BigQuery
 * documentation</a>.
 */
public static void labelTable(
    String projectId,
    String datasetId,
    String tableId,
    String labelKey,
    String labelValue)
    throws IOException {

  // Authenticate requests using Google Application Default credentials.
  GoogleCredential credential = GoogleCredential.getApplicationDefault();
  credential = credential.createScoped(Arrays.asList("https://www.googleapis.com/auth/bigquery"));

  // Get a new access token.
  // Note that access tokens have an expiration. You can reuse a token rather than requesting a
  // new one if it is not yet expired.
  credential.refreshToken();
  String accessToken = credential.getAccessToken();

  // Set the content of the request.
  Table table = new Table();
  table.addLabel(labelKey, labelValue);
  HttpContent content = new JsonHttpContent(JSON_FACTORY, table);

  // Send the request to the BigQuery API.
  String urlFormat =
      "https://www.googleapis.com/bigquery/v2/projects/%s/datasets/%s/tables/%s"
          + "?fields=labels&access_token=%s";
  GenericUrl url =
      new GenericUrl(String.format(urlFormat, projectId, datasetId, tableId, accessToken));
  HttpRequestFactory requestFactory = HTTP_TRANSPORT.createRequestFactory();
  HttpRequest request = requestFactory.buildPostRequest(url, content);
  request.setParser(JSON_FACTORY.createJsonObjectParser());

  // Workaround for transports which do not support PATCH requests.
  // See: http://stackoverflow.com/a/32503192/101923
  request.setHeaders(new HttpHeaders().set("X-HTTP-Method-Override", "PATCH"));
  HttpResponse response = request.execute();

  // Check for errors.
  if (response.getStatusCode() != 200) {
    throw new RuntimeException(response.getStatusMessage());
  }

  Table responseTable = response.parseAs(Table.class);
  System.out.printf(
      "Updated label \"%s\" with value \"%s\"\n",
      labelKey, responseTable.getLabels().get(labelKey));
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').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

添加作业标签

要通过命令行向查询作业添加标签,您可以使用命令行工具的 --label 标志。命令行工具仅支持向查询作业添加标签。

要向作业添加标签,您也可以在通过 API 提交作业时,调用 jobs.insert 方法时并在作业配置中指定 labels 属性。API 可用于向任何作业类型添加标签。

您不能为待处理、正在运行或已完成的作业添加标签或更新标签。

向作业添加标签后,标签会包含在您的结算数据中。

所需权限

向作业添加标签不需要特殊权限。如果您具有 jobs.create 权限,则可以在提交作业时向作业添加标签。

要运行某个作业,您必须具有 bigquery.jobs.create 权限。 BigQuery 自动创建的作业需要 bigquery.jobs.create 权限,您通过编程方式运行的作业也需要这些权限。

要运行 BigQuery 作业,请向您的用户或服务帐号授予 bigquery.jobs.create 权限,也可以向您的帐号授予包含 bigquery.jobs.create 权限的项目级层预定义 IAM 角色。以下预定义的 IAM 角色包含 bigquery.jobs.create 权限:

要详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问控制

向作业添加标签

要向作业添加标签,请执行以下操作:

Console

Console BigQuery 网页界面不支持向作业添加标签。

经典版界面

经典版 BigQuery 网页界面不支持向作业添加标签。

命令行

要向查询作业添加标签,请发出带 --label 标志的 bq query 命令。重复使用该标志可添加多个标签。--nouse_legacy_sql 标志表示您的查询采用标准 SQL 语法。

bq query --label [KEY:VALUE] --nouse_legacy_sql '[QUERY]'

其中:

  • [KEY:VALUE] 对应于要将其添加到查询作业的标签的键值对。键必须是唯一的。要向某个查询作业添加多个标签,请重复使用 --label 标志并为每个标签指定唯一键。
  • [QUERY] 是一条有效的标准 SQL 查询。

示例:

要向查询作业添加标签,请输入:

    bq query --label department:shipping --nouse_legacy_sql 'SELECT column1, column2 FROM `mydataset.mytable`'

要向某个查询作业添加多个标签,请重复使用 --label 标志并为每个标签指定唯一键。例如,要将 department:shipping 标签和 cost_center:logistics 标签添加到查询作业,请输入:

    bq query --label department:shipping --label cost_center:logistics --nouse_legacy_sql 'SELECT column1, column2 FROM `mydataset.mytable`'

API

要向作业添加标签,请调用 jobs.insert 方法并填充作业资源的 labels 属性。您可以使用 API 向任何作业类型添加标签。

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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
}

创建标记

如果一个标签的键为空值,则此标签用作标记。您可以创建一个未设定值的新标签,也可以将现有标签转变为标记。

如果您需要为资源添加标签,但不需要采用键值格式,则可以采用标记。例如,如果一个表包含由多个部门(支持、开发等)使用的测试数据,您可以将 test_data 标记添加到该表,以作识别之用。

要创建标记,请执行以下操作:

Console

  1. 在网页界面,选择相应资源(数据集、表或视图)。

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

    表详细信息

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

    标签铅笔

  4. 修改标签对话框中:

    • 点击添加标签
    • 输入新键并将值留空。要应用更多标记,请点击添加标签并重复。
    • 点击更新以保存更改。

经典版界面

选项 1:手动修改标签

  1. 在网页界面,选择相应资源(数据集、表或视图)。

  2. 对于数据集,系统会自动打开 Dataset Details 页面。对于表和视图,点击 Details 以打开详情页面。

  3. 在详情页面,点击 Labels 右侧的 Edit

  4. Edit Labels 对话框中:

    • 输入新键并将值留空。要应用更多标记,请点击 Add Label
    • 点击 OK

      添加标记

选项 2:使用 DDL 语句

借助数据定义语言 (DDL) 语句,您可以使用标准 SQL 查询语法创建并修改表和视图。

详细了解如何使用数据定义语言语句

  1. 点击 Compose query

  2. New Query 文本区域中输入 DDL 语句。

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       labels=[("tag1", ""), ("tag2", "")]
     )
     

命令行

要将标记添加到现有资源,请使用带 set_label 标志的 bq update 命令。指定键并在其后加上英文冒号,但不指定值。

bq update --set_label [KEY]: [RESOURCE_ID]

其中:

  • [KEY] 是要用作标记的标签键。
  • [RESOURCE_ID] 是有效的数据集、表或视图名称。如果资源在默认项目以外的项目中,请按以下格式添加相应项目 ID:[PROJECT_ID]:[DATASET]

示例:

输入以下命令可为 mydataset.mytable 创建 test_data 标记。mydataset 在默认项目中。

bq update --set_label test_data: mydataset

API

调用 datasets.patch 方法或 tables.patch 方法,然后在数据集资源表资源中添加标签,并将标签的值设置为空字符串 ("")。您可以将现有标签转变为标记,方法是将其值替换为空字符串。

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

查看标签

要查看标签,您可以使用 BigQuery 网页界面或命令行工具的 bq show 命令,也可以调用 datasets.gettables.get API 方法。由于视图被视为表资源,因此您可以使用 tables.get 方法来获取视图和表的标签信息。

所需权限

查看标签所需的权限取决于您访问的具体资源类型。

数据集权限

要获取数据集的相关信息,您必须分配有数据集级层 READER 角色,或者必须分配有包含 bigquery.datasets.get 权限的项目级层 IAM 角色。除了 bigquery.jobUser,其他所有预定义的项目级层 IAM 角色都具有 bigquery.datasets.get 权限。

此外,被指定为 bigquery.user 角色的用户具有 bigquery.datasets.create 权限。这样,被指定为 bigquery.user 角色的用户可以获取用户创建的任何数据集的相关信息。在被指定为 bigquery.user 角色的用户创建数据集后,系统将为该用户授予对该数据集的 OWNER 访问权限。凭借对数据集的 OWNER 访问权限,用户可以完全掌控该数据集。

要详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问控制。要详细了解数据集级层角色,请参阅数据集的初始角色

表和视图权限

要获取有关表的信息,您必须被指定为数据集的 READER 角色,或必须被指定为包含 bigquery.tables.get 权限的预定义的项目级层 IAM 角色。如果您拥有项目级层的 bigquery.tables.get 权限,则可获取项目中所有表的相关信息。除了 bigquery.userbigquery.jobUser,其他所有预定义的项目级 IAM 角色都具有 bigquery.tables.get 权限。

此外,被指定为 bigquery.user 角色的用户具有 bigquery.datasets.create 权限。这样,被指定为 bigquery.user 角色的用户可以获取用户创建的任何数据集内的表和视图的相关信息。在被指定为 bigquery.user 角色的用户创建数据集后,系统将为该用户授予对该数据集的 OWNER 访问权限。凭借对数据集的 OWNER 访问权限,用户可以完全掌控该数据集以及其中的所有表和视图。

要详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问控制。要详细了解数据集级层角色,请参阅数据集的初始角色

作业权限

要获取作业数据和元数据,您必须具有 bigquery.jobs.get 权限。以下预定义的项目级 IAM 角色包含 bigquery.jobs.get 权限:

如果您向某个帐号授予 bigquery.admin 角色,则该用户可以查看项目中的所有作业数据,无论作业的提交者是谁。

以下角色仅对自己创建的作业具有 bigquery.jobs.get 权限。此类用户只能查看自己提交的作业的数据:

要详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问控制

查看数据集、表和视图标签

要查看资源的标签,请执行以下操作:

Console

  1. 在 BigQuery 网页界面,选择相应资源(数据集、表或视图)。

  2. 对于数据集,系统会自动打开“数据集详情”页面。对于表和视图,点击详情以打开详情页面。标签信息将显示在资源的信息表中。

    表详细信息

经典版界面

  1. 在 BigQuery 网页界面,选择相应资源(数据集、表或视图)。

  2. 对于数据集,系统会自动打开 Dataset Details 页面。对于表和视图,点击 Details 以打开详情页面。标签信息将显示在资源的信息表中。

命令行

使用带有资源 ID 的 bq show 命令。--format 标记可以用于控制输出。如果资源位于默认项目以外的项目中,请按以下格式添加相应项目 ID:[PROJECT_ID]:[DATASET]。为确保可读性,可通过将 --format 标记设置为 pretty 来控制输出。

bq show --format=pretty [RESOURCE_ID]

其中,[RESOURCE_ID] 是有效的数据集、表或视图名称。

示例:

输入以下命令可显示默认项目中 mydataset 的标签。

bq show --format=pretty mydataset

输入以下命令可显示 mydataset.mytable 的标签。 mydataset 属于 myotherproject,而非默认项目。

bq show --format=pretty myotherproject:mydataset.mytable

API

调用 datasets.get 方法或 tables.get 方法。响应包含与该资源关联的所有标签。

或者,您可以使用 datasets.list 查看多个数据集或 tables.list 的标签,以查看多个表和视图的标签。

由于视图被视为表资源,因此您可以使用 tables.gettables.list 方法来查看视图和表的标签信息。

Go

此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。
// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
meta, err := client.Dataset(datasetID).Metadata(ctx)
if err != nil {
	return err
}
fmt.Fprintf(w, "Dataset %s labels:\n", datasetID)
if len(meta.Labels) == 0 {
	fmt.Fprintln(w, "Dataset has no labels defined.")
	return nil
}
for k, v := range meta.Labels {
	fmt.Fprintf(w, "\t%s:%s\n", k, v)
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
dataset = client.get_dataset(dataset_ref)  # API request

# View dataset labels
print("Dataset ID: {}".format(dataset_id))
print("Labels:")
if dataset.labels:
    for label, value in dataset.labels.items():
        print("\t{}: {}".format(label, value))
else:
    print("\tDataset has no labels defined.")

查看作业标签

提交查询作业后,作业标签不会出现在 BigQuery 网页界面中。要查看作业的标签,请发出 bq show -j [JOB_ID] 命令。

Console

您不能使用 Console BigQuery 网页界面查看作业标签。

经典版界面

您不能使用经典版 BigQuery 网页界面查看作业标签。

CLI

要使用 bq 命令行工具查看某个查询作业的标签,请输入带有该查询作业的作业 ID 的 bq show -j 命令。--format 标志可用于控制输出。例如,如果查询作业的作业 ID 为 bqjob_r1234d57f78901_000023746d4q12_1,请输入以下命令:

bq show -j --format=pretty bqjob_r1234d57f78901_000023746d4q12_1

输出应如下所示:

+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| Job Type |  State  |   Start Time    | Duration |    User Email     | Bytes Processed | Bytes Billed |        Labels        |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+
| query    | SUCCESS | 03 Dec 15:00:41 | 0:00:00  | email@example.com | 255             | 10485760     | department:shipping  |
|          |         |                 |          |                   |                 |              | costcenter:logistics |
+----------+---------+-----------------+----------+-------------------+-----------------+--------------+----------------------+

API

调用 jobs.get 方法。响应包含与该资源关联的所有标签。

使用标签过滤数据集

要根据标签过滤数据集,请创建过滤规范,以在 bq 命令行工具或使用以下语法的 BigQuery API 中使用:

    "field[:value][ field[:value]..."

其中:

  • fieldlabels.[KEY] 表示, 其中 [KEY] 是标签键。
  • value 是可选的标签值。

目前,您无法根据过滤规范列出表或视图。

限制

过滤规范具有以下限制:

  • 仅支持 AND 逻辑运算符。系统会将用空格分隔的比较视为具有隐式 AND 运算符。
  • 目前,唯一符合过滤条件的字段是“labels.key”,其中“key”是标签的名称。
  • 过滤条件最多可包含 10 个表达式。
  • 过滤时会区分大小写。
  • 您无法使用过滤规范过滤表和视图。
  • 目前,您无法使用 BigQuery 网页界面过滤数据集。

过滤规范示例

要列出具有 department:shipping 标签的数据集,请使用以下过滤规范:

labels.department:shipping

要列出具有多个标签的数据集,请使用空格分隔键值对。系统会将空格视为逻辑 AND 运算符。例如,要列出具有 department:shipping 标签和 location:usa 标签的数据集,请使用以下过滤规范:

labels.department:shipping labels.location:usa

您可以单独对键进行过滤,而不是匹配键值对。以下过滤规范可列出所有具有 department 标签的数据集,无论其值如何:

labels.department

等效过滤规范使用星号来表示与 department 键相关的所有可能值:

labels.department:*

您还可以在过滤规范中使用标记。例如,要列出具有 department:shipping 标签和 test_data 标记的数据集,请使用以下过滤规范:

labels.department:shipping labels.test_data

生成已过滤的列表

要生成已过滤的数据集列表,请执行以下操作:

Console

目前,您无法使用 Console BigQuery 网页界面过滤数据集。

经典版界面

目前,您无法使用经典版 BigQuery 网页界面过滤数据集。

命令行

发出带 --filter 标记的 bq ls 命令。如果您要列出默认项目以外的某个项目中的数据集,请指定 --project_id 标记。

bq ls --filter "[FILTER_SPECIFICATION]" --project_id [PROJECT_ID]

其中:

  • [FILTER_SPECIFICATION]有效的过滤条件规范。命令行工具会返回符合过滤要求的数据集列表。
  • [PROJECT_ID] 是您的项目 ID。

示例:

输入以下命令可列出默认项目中具有 department:shipping 标签的数据集:

bq ls --filter "labels.department:shipping"

输入以下命令可列出默认项目中具有 department:shipping 标签和 test_data 标记的数据集。

bq ls --filter "labels.department:shipping labels.test_data"

输入以下命令可列出 myotherproject 中具有 department:shipping 标签的数据集:

bq ls --filter "labels.department:shipping" --project_id myotherproject

API

调用 datasets.list API 方法,并使用 filter 属性提供过滤条件规范。

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
it := client.Datasets(ctx)
it.Filter = "labels.color:green"
for {
	dataset, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "dataset: %s\n", dataset.DatasetID)
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()

# The following label filter example will find datasets with an
# arbitrary 'color' label set to 'green'
label_filter = "labels.color:green"
datasets = list(client.list_datasets(filter=label_filter))

if datasets:
    print("Datasets filtered by {}:".format(label_filter))
    for dataset in datasets:  # API request(s)
        print("\t{}".format(dataset.dataset_id))
else:
    print("No datasets found with this filter.")

后续步骤

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面