本文档介绍了如何在 BigQuery 中更新数据集属性。创建数据集后,您可以更新以下数据集属性:
所需权限
如需更新数据集属性,您必须至少具备 bigquery.datasets.update
和 bigquery.datasets.get
权限。以下预定义 IAM 角色具有 bigquery.datasets.update
和 bigquery.datasets.get
权限:
bigquery.dataOwner
bigquery.admin
此外,如果用户具有 bigquery.datasets.create
权限,则当该用户创建数据集时,系统会为其授予该数据集的 bigquery.dataOwner
访问权限。借助 bigquery.dataOwner
访问权限,用户可以更新其创建的数据集的属性。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问权限控制。
更新数据集说明
您可以通过以下方式更新表的说明:
- 使用 Cloud Console。
- 使用
bq
命令行工具的bq update
命令。 - 调用
datasets.patch
API 方法。 - 使用客户端库。
如需更新数据集的说明,请执行以下操作:
控制台
在探索器面板中,展开您的项目并选择数据集。
在详细信息页面中,点击说明旁边的铅笔图标以修改说明文本。
在对话框中输入说明或修改现有说明。点击更新以保存新的说明文本。
bq
发出带 --description
标志的 bq update
命令。如果您要更新非默认项目中的数据集,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
bq update \ --description "string" \ project_id:dataset
替换以下内容:
string
:描述数据集的文本,括在英文双引号内project_id
:您的项目 IDdataset
:您要更新的数据集的名称
示例:
输入以下命令可将 mydataset
的说明更改为“Description of mydataset”。mydataset
属于默认项目。
bq update --description "Description of mydataset" mydataset
输入以下命令可将 mydataset
的说明更改为“Description of mydataset”。该数据集属于 myotherproject
,而非默认项目。
bq update \
--description "Description of mydataset" \
myotherproject:mydataset
API
调用 datasets.patch
并更新数据集资源中的 description
属性。由于 datasets.update
方法会替换整个数据集资源,因此最好使用 datasets.patch
方法。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
使用 Dataset.toBuilder() 方法,基于现有数据集实例创建 Dataset.Builder 实例。配置数据集构建器对象。使用 Dataset.Builder.build() 方法构建更新的数据集,然后调用 Dataset.update() 方法向 API 发送更新。Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
配置 Dataset.description 属性,并调用 Client.update_dataset() 向 API 发送更新。更新默认表到期时间
您可以通过以下方式更新数据集的默认表到期时间:
- 使用 Cloud Console。
- 使用
bq
命令行工具的bq update
命令。 - 调用
datasets.patch
API 方法。 - 使用客户端库。
您可以在数据集级层设置默认的表到期时间,也可以在创建表时设置表的到期时间。如果在创建表时设置了其过期时间,则系统会忽略数据集的默认表过期时间。如果未在数据集级层设置默认的表到期时间,也未在创建表时设置表到期时间,则该表永不过期,您必须手动删除该表。
更新数据集的默认表过期时间设置时:
- 如果您将此设置的值从
Never
更改为由您定义的过期时间,那么对于数据集中的任何现有表而言,除非您在创建该表时为其设置了过期时间,否则该表不会过期。 - 如果您更改默认的表过期时间值,那么任何现有表将应用原始表过期时间设置。 而对于在数据集中创建的任何新表,除非您在创建该表时为其指定了不同的表过期时间,否则该表将应用新的表过期时间设置。
默认表过期时间值的表示方式有所不同,具体取决于该值的设置位置。请根据自己所需的细化程度选择适当的方法:
- 在 Cloud Console 中,过期时间以天为单位表示。
- 在
bq
命令行工具中,到期时间以秒为单位表示。 - 在 API 中,到期时间以毫秒为单位表示。
如需更新数据集的默认到期时间,请执行以下操作:
控制台
在探索器面板中,展开您的项目并选择数据集。
在详细信息页面中,点击数据集信息旁边的铅笔图标以修改到期时间。
在数据集信息对话框的默认表过期时间部分中,输入创建表后的天数的值。
点击保存。
bq
如需更新数据集中新创建的表的默认到期时间,请输入带 --default_table_expiration
标志的 bq update
命令。如果您要更新非默认项目中的数据集,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
bq update \ --default_table_expiration integer \ project_id:dataset
请替换以下内容:
integer
:新创建的表的默认生命周期(以秒为单位)。最小值为 3600 秒(一小时)。到期时间以当前世界协调时间 (UTC) 加上这个整数值为准。 指定0
可移除现有到期时间。在数据集中创建的任何表都会在创建之时起的integer
秒后删除。如果您在创建表时未设置表到期时间,则系统会应用此值。project_id
:您的项目 ID。dataset
:您要更新的数据集的名称。
示例:
输入以下命令可将在 mydataset
中创建的新表的默认表过期时间设置为从当前时间算起两小时(7200 秒)。该数据集在默认项目中。
bq update --default_table_expiration 7200 mydataset
输入以下命令可将在 mydataset
中创建的新表的默认表过期时间设置为从当前时间算起两小时(7200 秒)。该数据集属于 myotherproject
,而非默认项目。
bq update --default_table_expiration 7200 myotherproject:mydataset
API
调用 datasets.patch
并更新数据集资源中的 defaultTableExpirationMs
属性。在 API 中,到期时间以毫秒为单位表示。由于 datasets.update
方法会替换整个数据集资源,因此最好使用 datasets.patch
方法。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
使用 Dataset.toBuilder() 方法,基于现有数据集实例创建 Dataset.Builder 实例。配置数据集构建器对象。使用 Dataset.Builder.build() 方法构建更新的数据集,然后调用 Dataset.update() 方法向 API 发送更新。使用 Dataset.Builder.setDefaultTableLifetime() 方法配置默认到期时间。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
配置 Dataset.default_table_expiration_ms 属性,然后调用 Client.update_dataset() 向 API 发送更新。更新默认分区到期时间
您可以通过以下方式更新数据集的默认分区到期时间:
- 使用
bq
命令行工具的bq update
命令。 - 调用
datasets.patch
API 方法。 - 使用客户端库。
Cloud Console 目前不支持设置或更新数据集的默认分区到期时间。
您可以在数据集级层设置默认分区到期时间,该到期时间会影响所有新建的分区表,也可以在创建分区表时设置各个表的分区到期时间。如果在数据集级层设置默认分区到期时间,并在数据集级层设置默认表到期时间,则新分区表将只有分区到期时间。如果同时设置了这两个选项,则默认分区到期时间将覆盖默认表到期时间。
如果您在创建分区表时设置了分区到期时间,则该值将覆盖数据集级层的默认分区到期时间(如果存在)。
如果您未在数据集级层设置默认分区到期时间,并且在创建表时未设置分区到期时间,则分区将永不过期,您必须手动删除分区。
如果您为数据集设置了默认分区到期时间,则该到期时间将应用于数据集中创建的所有分区表中的所有分区。如果您为表设置了分区到期时间,则该到期时间将应用于指定的表中创建的所有分区。目前,您不能将不同到期时间应用于同一个表中的不同分区。
在您更新数据集的默认分区到期时间设置时:
- 如果您将值从
never
更改为定义的到期时间,则除非在创建分区表时为其设置了分区到期时间,否则在数据集的分区表中已存在的所有分区都将不会过期。 - 如果您要更改默认分区到期时间的值,则现有分区表中的所有分区都将根据原始默认分区到期时间过期。除非您在创建分区表时指定了其他分区到期时间,否则数据集中创建的所有新分区表都将应用新的默认分区到期时间。
默认分区到期时间值的表示方式有所不同,具体取决于该值的设置位置。请根据自己所需的细化程度选择适当的方法:
- 在
bq
命令行工具中,到期时间以秒为单位表示。 - 在 API 中,到期时间以毫秒为单位表示。
如需更新数据集的默认分区到期时间,请执行以下操作:
控制台
目前,Cloud Console 不支持更新数据集的默认分区到期时间。
bq
如需更新数据集的默认到期时间,请输入带 --default_partition_expiration
标志的 bq update
命令。如果您要更新非默认项目中的数据集,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
bq update \ --default_partition_expiration integer \ project_id:dataset
请替换以下内容:
integer
:新创建的分区表中分区的默认生命周期(以秒为单位)。此标志没有最小值。指定0
可移除现有到期时间。新创建的分区表中的所有分区都会在分区创建日期(按世界协调时间 (UTC) 计算)之时起的integer
秒后删除。如果您在创建表时未设置分区到期时间,则系统会应用此值。project_id
:您的项目 ID。dataset
:您要更新的数据集的名称。
示例:
输入以下命令可将在 mydataset
中创建的新分区表的默认分区到期时间设置为 26 小时(93600 秒)。该数据集在默认项目中。
bq update --default_partition_expiration 93600 mydataset
输入以下命令可将在 mydataset
中创建的新分区表的默认分区到期时间设置为 26 小时(93600 秒)。该数据集属于 myotherproject
,而非默认项目。
bq update --default_partition_expiration 93600 myotherproject:mydataset
API
调用 datasets.patch
并更新数据集资源中的 defaultPartitionExpirationMs
属性。到期时间以毫秒为单位表示。由于 datasets.update
方法会替换整个数据集资源,因此最好使用 datasets.patch
方法。
更新数据集访问权限控制
更新数据集访问权限控制的过程与分配对数据集的访问权限控制的过程非常相似。在使用 Cloud Console 或 bq
命令行工具创建数据集期间,无法应用访问权限控制。您必须先创建数据集,然后才能更新数据集的访问权限控制。借助 API,您可以通过调用 datasets.patch 方法来更新数据集访问权限控制。
更新数据集的访问权限控制时,您可以修改以下实体的访问权限:
- Google 帐号电子邮件:向某个 Google 帐号授予对数据集的访问权限。
- Google 群组:向某个 Google 群组的所有成员授予对数据集的访问权限。
- Google Apps 网域:向某个 Google 网域中的所有用户和群组授予对数据集的访问权限。
- 服务帐号:向某个服务帐号授予对数据集的访问权限。
- 任何人:输入
allUsers
可向公众授予访问权限。 - 所有 Google 帐号:输入
allAuthenticatedUsers
可向任何已登录到 Google 帐号的用户授予访问权限。 - 授权视图:向某个授权视图授予对数据集的访问权限。
如需更新数据集的访问权限控制,请执行以下操作:
控制台
在探索器面板中,展开您的项目并选择数据集。
点击共享数据集。
在共享数据集对话框中,展开条目,然后点击删除图标(垃圾桶),即可删除现有条目。
在共享数据集对话框中,按照如下方式添加新条目:
在添加成员框中输入实体。
对于选择角色,从列表中选择适当的 IAM 角色。如需详细了解分配给每个预定义 BigQuery 角色的权限,请参阅预定义的角色和权限页面。
点击添加。
要添加已获授权的视图,请点击已获授权的视图标签页,然后输入项目、数据集和视图,再点击添加。
添加完或删除完访问权限控制后,点击完成。
bq
使用
show
命令将现有数据集信息(包括访问权限控制设置)写入 JSON 文件。如果数据集不属于默认项目,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。bq show \ --format=prettyjson \ project_id:dataset > path_to_file
替换以下内容:
project_id
:您的项目 ID。dataset
:您的数据集的名称。path_to_file
:本地机器上 JSON 文件的路径。
示例:
输入以下命令可将
mydataset
的访问权限控制写入 JSON 文件。mydataset
属于默认项目。bq show --format=prettyjson mydataset > /tmp/mydataset.json
输入以下命令可将
mydataset
的访问权限控制写入 JSON 文件。mydataset
属于myotherproject
。bq show --format=prettyjson \ myotherproject:mydataset > /tmp/mydataset.json
对 JSON 文件的
"access"
部分进行更改。您可以添加或移除任意specialGroup
条目:projectOwners
、projectWriters
、projectReaders
、allAuthenticatedUsers
。还可以添加、移除或修改以下任一项:userByEmail
、groupByEmail
、domain
。例如,某个数据集的 JSON 文件的 access 部分可能如下所示:
{ "access": [ { "role": "READER", "specialGroup": "projectReaders" }, { "role": "WRITER", "specialGroup": "projectWriters" }, { "role": "OWNER", "specialGroup": "projectOwners" } { "role": "READER", "specialGroup": "allAuthenticatedUsers" } { "role": "READER", "domain": "[DOMAIN_NAME]" } { "role": "WRITER", "userByEmail": "[USER_EMAIL]" } { "role": "READER", "groupByEmail": "[GROUP_EMAIL]" } ], }
修改完成后,运行
update
命令,并用--source
标志包括该 JSON 文件。如果数据集不属于默认项目,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。bq update --source path_to_file project_id:dataset
替换以下内容:
path_to_file
:本地机器上 JSON 文件的路径。project_id
:您的项目 ID。dataset
:您的数据集的名称。
示例:
输入以下命令可更新
mydataset
的访问权限控制。mydataset
属于默认项目。bq update --source /tmp/mydataset.json mydataset
输入以下命令可更新
mydataset
的访问权限控制。mydataset
属于myotherproject
。bq update --source /tmp/mydataset.json myotherproject:mydataset
如需验证您的访问权限控制发生了变化,请再次输入
show
命令,但不要将信息写入文件。bq show --format=prettyjson dataset
或
bq show --format=prettyjson project_id:dataset
API
调用 datasets.patch
并更新数据集资源中的 access
属性。
由于 datasets.update
方法会替换整个数据集资源,因此 datasets.patch
是更新访问权限控制的首选方法。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
使用 Dataset.toBuilder() 方法,基于现有数据集实例创建 Dataset.Builder 实例。配置数据集构建器对象。使用 Dataset.Builder.build() 方法构建更新的数据集,然后调用 Dataset.update() 方法向 API 发送更新。使用 Dataset.Builder.setAcl() 方法配置访问权限控制。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
使用数据集的访问控制设置 dataset.access_entries 属性。然后调用 client.update_dataset() 函数来更新该属性。