本页面介绍了如何为 BigQuery 资源添加标签。
添加数据集标签
在创建 BigQuery 数据集时,您可以使用 bq
命令行工具的 bq mk
命令或调用 datasets.insert
API 方法来为该数据集添加标签。目前,您不能向通过 Cloud Console 创建的数据集添加标签。
本页面介绍如何在创建数据集后向其添加标签。如需详细了解如何在创建数据集时添加标签,请参阅创建数据集。
在创建数据集后添加标签的方法如下:
- 使用 Cloud Console
- 使用
bq
命令行工具的bq update
命令 - 调用
datasets.patch
API 方法 - 使用客户端库
向数据集添加标签时,标签不会传播到该数据集中的资源。表或视图不会继承数据集标签。向数据集添加标签后,标签会包含在存储空间结算数据中,但您不会在与作业相关的结算数据中看到数据集标签。
所需权限
如需为现有数据集添加标签,您必须至少具有 bigquery.datasets.update
权限。以下预定义的 IAM 角色包含 bigquery.datasets.update
权限:
bigquery.dataOwner
bigquery.admin
此外,如果用户具有 bigquery.datasets.create
权限,则当该用户创建数据集时,系统会为其授予该数据集的 bigquery.dataOwner
访问权限。具备 bigquery.dataOwner
访问权限的用户可为其数据集添加标签。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
为数据集添加标签
如需在创建数据集后为其添加标签,请执行以下操作:
控制台
在 Cloud Console 中,选择相应的数据集。
在数据集详细信息页面上,点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作:
- 点击添加标签。
- 输入键和值以添加标签。如需应用更多标签,请点击添加标签。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
- 修改现有键或值以更新标签。
- 点击更新以保存更改。
bq
如需为现有数据集添加标签,请发出带 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
指定为标签键。例如,如要为默认项目中的 mydataset
添加 department:shipping
标签,请输入以下命令:
bq update --set_label department:shipping mydataset
如需为数据集添加多个标签,请重复使用 set_label
标志并为每个标签指定唯一键。例如,如要为默认项目中的 mydataset
添加 department:shipping
标签和 cost_center:logistics
标签,请输入以下命令:
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 参考文档。
Java
此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
添加表和视图标签
在创建表或视图时向其添加标签的方法如下:
- 使用
bq
命令行工具的bq mk
命令 - 调用
tables.insert
API 方法
本页面介绍如何向现有表或视图添加标签。如需详细了解如何在创建表或视图时添加标签,请参阅创建表或创建视图。
在创建表或视图后向其添加标签的方法如下:
- 使用 Cloud Console
- 使用
bq
命令行工具的bq update
命令 - 调用
tables.patch
API 方法 - 使用客户端库
由于视图被视为表资源,因此您可以使用 tables.patch
方法来修改视图和表。
所需权限
如需为现有表或视图添加标签,您必须至少具有 bigquery.tables.update
和 bigquery.tables.get
权限。以下预定义 IAM 角色具有 bigquery.tables.update
和 bigquery.tables.get
权限:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
此外,如果用户具有 bigquery.datasets.create
权限,则当该用户创建数据集时,系统会为其授予该数据集的 bigquery.dataOwner
访问权限。具备 bigquery.dataOwner
访问权限的用户可以为其数据集中的表和视图添加标签。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
为表或视图添加标签
如需为现有表或视图添加标签,请执行以下操作:
控制台
在 Cloud Console 中选择表或视图。
点击详细信息标签页。
点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作:
- 点击添加标签。
- 输入键和值以添加标签。如需应用更多标签,请点击添加标签。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
- 修改现有键或值以更新标签。
- 点击更新以保存更改。
SQL
借助数据定义语言 (DDL) 语句,您可以使用标准 SQL 查询语法创建和修改表和视图。
详细了解如何使用数据定义语言语句。
如需在 Cloud Console 中使用 DDL 语句添加标签,请执行以下操作:
点击编写新查询。
在查询编辑器文本区域中,输入您的 DDL 语句。
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("department", "shipping"), ("cost_center", "logistics")] )
点击运行查询。
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
:您要为其添加标签的表或视图的名称。
示例:
如需添加表标签来跟踪部门,请输入 bq update
命令并将 department
指定为标签键。例如,如要为默认项目中的 mytable
添加 department:shipping
标签,请输入以下命令:
bq update --set_label department:shipping mydataset.mytable
如需添加视图标签来跟踪部门,请输入 bq update
命令并将 department
指定为标签键。例如,如要为默认项目中的 myview
添加 department:shipping
标签,请输入以下命令:
bq update --set_label department:shipping mydataset.myview
如需为表或视图添加多个标签,请重复使用 set_label
标志并为每个标签指定唯一键。例如,如要为默认项目中的 mytable
添加 department:shipping
标签和 cost_center:logistics
标签,请输入以下命令:
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 参考文档。
Java
此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
为作业添加标签
您可以通过命令行使用 bq
命令行工具的 --label
标志,为查询作业添加标签。bq
工具仅支持向查询作业添加标签。
您也可以在通过 API 提交作业时为该作业添加标签,具体做法是调用 jobs.insert
方法并在作业配置中指定 labels
属性。API 支持为任何类型的作业添加标签。
您不能为待处理、正在运行或已完成的作业添加标签或更新标签。
向作业添加标签后,标签会包含在您的结算数据中。
所需权限
为作业添加标签不需要特殊权限。如果您具有 bigquery.jobs.create
权限,则可在提交作业时为其添加标签。
如要运行作业,您必须至少具有 bigquery.jobs.create
权限。
BigQuery 自动创建的作业和您通过编程方式运行的作业都需要 bigquery.jobs.create
权限。
以下预定义的 IAM 角色包含 bigquery.jobs.create
权限:
bigquery.user
bigquery.jobUser
bigquery.admin
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
为作业添加标签
如需为作业添加标签,请执行以下操作:
控制台
Cloud Console 不支持为作业添加标签。
bq
如需为查询作业添加标签,请发出带 --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 为任何类型的作业添加标签。
添加标记
如果一个标签的键没有相应的值,则此标签用作标记。您可以创建一个未设定值的新标签,也可以将现有标签转变为标记。
如果您需要为资源添加标签,但不需要采用键值格式,则可以采用标记。例如,如果您的表包含由多个群组(支持、开发等)使用的测试数据,您可以为该表添加 test_data
标记,以作识别之用。
如需添加标记,请执行以下操作:
控制台
在 Cloud Console 中,选择相应的资源(数据集、表或视图)。
对于数据集,系统会自动打开“数据集详情”页面。对于表和视图,点击详细信息以打开详情页面。
在详情页面上,点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作:
- 点击添加标签。
- 输入新键并将值留空。如需应用更多标记,请点击添加标签并重复。
- 点击更新以保存更改。
SQL
借助数据定义语言 (DDL) 语句,您可以使用标准 SQL 查询语法创建和修改表及视图。
详细了解如何使用数据定义语言语句。
如需在 Cloud Console 中使用 DDL 语句添加标记,请执行以下操作:
点击编写新查询。
在查询编辑器文本区域中,输入您的 DDL 语句。
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("tag1", ""), ("tag2", "")] )
点击运行查询。
bq
如需为现有资源添加标记,请使用带 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 资源查看标签。
- 了解如何针对 BigQuery 资源更新标签。
- 了解如何使用标签过滤资源。
- 了解如何针对 BigQuery 资源删除标签。
- 参阅 Resource Manager 文档中的使用标签。