更新数据集属性

本文档介绍了如何在 BigQuery 中更新数据集属性。创建数据集后,您可以更新以下数据集属性:

所需权限

要更新数据集属性,您必须具有数据集级层的 OWNER 访问权限,或者必须拥有具备 bigquery.datasets.update 权限的项目级层 IAM 角色。以下预定义的项目级层 IAM 角色具有 bigquery.datasets.update 权限:

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

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

更新数据集说明

您可以通过以下方式更新数据集的说明:

  • 使用 GCP Console 或经典版 BigQuery 网页界面
  • 使用 bq update CLI 命令
  • 调用 datasets.patch API 方法

要更新数据集的说明,请执行以下操作:

Console

  1. 资源窗格中,选择您的数据集。

  2. 详细信息页面中,点击说明旁边的铅笔图标以修改说明文本。

    查询设置

  3. 在对话框中输入说明或修改现有说明。点击更新以保存新的说明文本。

经典版界面

  1. 在导航窗格中,选择数据集。

  2. 数据集详细信息 (Dataset Details) 页面的说明 (Description) 部分中,点击描述此数据集 (Describe this dataset) 以打开说明框(如果该数据集没有相关说明)。如果该数据集已有相关说明,请点击现有说明文本。

  3. 在说明框中输入说明或修改现有说明。点击说明框以外的位置即可保存文本。

    数据集说明

CLI

发出带 --description 标志的 bq update 命令。如果您要更新非默认项目中的数据集,请按以下格式将相应项目 ID 添加到数据集名称中:[PROJECT_ID]:[DATASET]

bq update --description "[STRING]" [PROJECT_ID]:[DATASET]

其中:

  • [STRING] 是用于描述数据集的带引号文本。
  • [PROJECT_ID] 是您的项目 ID。
  • [DATASET] 是要更新的数据集的名称。

示例:

输入以下命令可将 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 参考文档

ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.DatasetMetadataToUpdate{
	Description: "Updated Description.",
}
if _, err = ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

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

创建 Dataset.Builder 实例(方式是基于现有 Dataset 实例并使用 Dataset.toBuilder() 方法)。配置数据集开发工具对象。使用 Dataset.Builder.build() 方法构建更新的数据集,并调用 Dataset.update() 方法将更新发送到 API。
Dataset oldDataset = bigquery.getDataset(datasetName);
DatasetInfo datasetInfo = oldDataset.toBuilder().setDescription(newDescription).build();
Dataset newDataset = bigquery.update(datasetInfo);

Python

Python

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

配置 Dataset.description 属性,并调用 Client.update_dataset() 将更新发送到 API。
from google.cloud import bigquery

# TODO(developer): 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)
dataset.description = "Updated description."
dataset = client.update_dataset(dataset, ["description"])

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with description '{}'.".format(
        full_dataset_id, dataset.description
    )
)

更新默认表到期时间

您可以通过以下方式更新数据集的默认表过期时间:

  • 使用 GCP Console 或经典版 BigQuery 网页界面
  • 使用 bq update CLI 命令
  • 调用 datasets.patch API 方法

您可以在数据集级层设置默认的表过期时间,也可以在创建表时设置表的过期时间。如果在创建表时设置了其过期时间,则系统会忽略数据集的默认表过期时间。如果您未在数据集级层设置默认的表过期时间,也未在创建表时设置表过期时间,则该表永远不会过期,且只能手动删除

更新数据集的默认表过期时间设置时:

  • 如果您将此设置的值从 Never 更改为定义的过期时间,那么对于数据集中的任何现有表而言,除非您在创建该表时为其设置了过期时间,否则该表不会过期。
  • 如果您更改默认的表过期时间值,那么任何现有表将应用原始表过期时间设置。而对于在数据集中创建的任何新表,除非您在创建该表时为其指定了不同的表过期日期,否则该表将应用新的表过期时间设置。

默认表过期时间值的表示方式有所不同,具体取决于该值的设置位置。请根据自己所需的细化程度选择适当的方法:

  • 在 GCP Console 和经典版 BigQuery 网页界面中,到期时间以天为单位表示。
  • 在命令行工具中,到期时间以秒数为单位表示。
  • 在 API 中,到期时间以毫秒为单位表示。

要更新数据集的默认到期时间,请执行以下操作:

Console

  1. 资源窗格中,选择您的数据集。

  2. 详细信息页面中,点击数据集信息旁边的铅笔图标以修改到期时间。

  3. 数据集信息对话框的默认表过期时间部分中,输入创建表后的天数的值。

  4. 点击保存

经典版界面

  1. 在导航窗格中,选择数据集。

  2. 数据集详细信息 (Dataset Details) 页面中,点击默认表过期时间 (Default Table Expiration) 右侧的详细信息 (Details) 部分中的修改

    表过期时间

  3. 更新过期时间 (Update Expiration) 对话框中,点击数据过期时间 (Data expiration) 部分中的剩余时间 (In),并以天数为单位输入过期时间。默认值为永不过期 (Never)。

CLI

要更新数据集中新创建表的默认过期时间,请输入带有 --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 属性。由于 datasets.update 方法会替换整个数据集资源,因此最好使用 datasets.patch 方法。

Go

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

ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.DatasetMetadataToUpdate{
	DefaultTableExpiration: 24 * time.Hour,
}
if _, err := client.Dataset(datasetID).Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

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

创建 Dataset.Builder 实例(方式是基于现有 Dataset 实例并使用 Dataset.toBuilder() 方法)。配置数据集开发工具对象。使用 Dataset.Builder.build() 方法构建更新的数据集,并调用 Dataset.update() 方法将更新发送到 API。

使用 Dataset.Builder.setDefaultTableLifetime() 方法配置默认到期时间。

Long beforeExpiration = dataset.getDefaultTableLifetime();

Long oneDayMilliseconds = 24 * 60 * 60 * 1000L;
DatasetInfo.Builder builder = dataset.toBuilder();
builder.setDefaultTableLifetime(oneDayMilliseconds);
bigquery.update(builder.build());  // API request.

Python

Python

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

配置 Dataset.default_table_expiration_ms 属性并调用 Client.update_dataset() 将更新发送到 API。
from google.cloud import bigquery

# TODO(developer): 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)
dataset.default_table_expiration_ms = 24 * 60 * 60 * 1000  # in milliseconds

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

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset {} with new expiration {}".format(
        full_dataset_id, dataset.default_table_expiration_ms
    )
)

更新默认分区到期时间

您可以通过下列方式更新数据集的默认分区到期时间:

目前,GCP Console 或经典版 BigQuery 网页界面不支持设置或更新数据集的默认分区到期时间。

您可以在数据集级层设置默认分区到期时间,该到期时间会影响所有新建的分区表,也可以在创建分区表时设置各个表的分区到期时间。如果在数据集级层设置默认分区到期时间,并在数据集级层设置默认表到期时间,则新分区表将只有分区到期时间。如果同时设置了这两个选项,则默认分区到期时间将覆盖默认表到期时间。

如果您在创建分区表时设置了分区到期时间,则该值将覆盖数据集级层的默认分区到期时间(如果存在)。

如果您未在数据集级层设置默认分区到期时间,并且在创建表时未设置分区到期时间,则分区将永不过期,您必须手动删除分区。

如果您为数据集设置了默认分区到期时间,则该到期时间将应用于数据集中创建的所有分区表中的所有分区。如果您为表设置了分区到期时间,则该到期时间将应用于指定的表中创建的所有分区。目前,您不能将不同到期时间应用于同一个表中的不同分区。

在您更新数据集的默认分区到期时间设置时:

  • 如果您将值从“永不过期”更改为定义的到期时间,则除非在创建分区表时为其设置了分区到期时间,否则在数据集的分区表中已存在的所有分区都将不会过期。
  • 如果您要更改默认分区到期时间的值,则现有分区表中的所有分区都将根据原始默认分区到期时间过期。除非您在创建分区表时指定了其他分区到期时间,否则数据集中创建的所有新分区表都将应用新的默认分区到期时间。

默认分区到期时间值的表示方式有所不同,具体取决于该值的设置位置。请根据自己所需的细化程度选择适当的方法:

  • 在命令行工具中,到期时间以秒数为单位表示。
  • 在 API 中,到期时间以毫秒为单位表示。

要更新数据集的默认分区到期时间,请执行以下操作:

Console

目前,GCP Console 不支持更新数据集的默认分区到期时间。

经典版界面

目前,经典版 BigQuery 网页界面不支持更新数据集的默认分区到期时间。

CLI

要更新数据集的默认到期时间,请输入带 --default_partition_expiration 标志的 bq update 命令。如果您要更新非默认项目中的数据集,请按以下格式将相应项目 ID 添加到数据集名称中:[PROJECT_ID]:[DATASET]

bq update --default_partition_expiration [INTEGER] [PROJECT_ID]:[DATASET]

其中:

  • [INTEGER] 是新建分区表中的分区的默认生命周期(以秒为单位)。此标志没有最小值。指定 0 可移除现有到期时间。在新建的分区表中创建的所有分区都会在分区创建日期之时起的 [INTEGER] 秒后删除。如果您在创建表时未设置分区到期时间,则系统会应用此值。
  • [PROJECT_ID] 是项目 ID。
  • [DATASET] 是要更新的数据集的名称。

示例:

输入以下命令可将在 mydataset 中创建的新分区表的默认分区到期时间设置为 26 小时(93,600 秒)。该数据集属于默认项目。

bq update --default_partition_expiration 93600 mydataset

输入以下命令可将在 mydataset 中创建的新分区表的默认分区到期时间设置为 26 小时(93,600 秒)。该数据集属于 myotherproject,而非默认项目。

bq update --default_partition_expiration 7200 myotherproject:mydataset

API

调用 datasets.patch 并更新数据集资源中的 defaultPartitionExpirationMs 属性。到期时间以毫秒为单位表示。由于 datasets.update 方法会替换整个数据集资源,因此最好使用 datasets.patch 方法。

更新数据集访问权限控制

更新数据集访问权限控制的过程与分配对数据集的访问权限控制的过程非常相似。使用 GCP Console、经典版 BigQuery 网页界面或命令行工具创建数据集期间,您无法应用访问权限控制。您必须先创建数据集,然后才能更新数据集的访问权限控制。借助 API,您可以通过调用 datasets.patch 方法来更新数据集访问权限控制。

更新数据集的访问权限控制时,您可以修改以下用户和群组的访问权限:

  • 用户(使用电子邮件)(User by e-mail) - 向个别 Google 帐号授予对数据集的访问权限
  • 群组(使用电子邮件)(Group by e-mail) - 向 Google 群组的所有成员授予对数据集的访问权限
  • 网域 - 向 Google Domains 中的所有用户和群组授予对数据集的访问权限
  • 所有经过身份验证的用户 (All Authenticated Users) - 向所有 Google 帐号拥有者授予对数据集的访问权限(将数据集设为公开)
  • 项目所有者 (Project Owners) - 向所有项目所有者授予对数据集的访问权限
  • 项目查看者 (Project Viewers) - 向所有项目查看者授予对数据集的访问权限
  • 项目编辑者 (Project Editors) - 向所有项目编辑者授予对数据集的访问权限
  • 已获授权的视图 - 向视图授予对数据集的访问权限

要更新数据集的访问权限控制,请执行以下操作:

Console

  1. 在界面导航面板的资源部分,点击您的数据集。

  2. 点击共享数据集

  3. 共享数据集对话框中,展开条目,然后点击删除图标(垃圾桶),即可删除现有条目。

  4. 共享数据集对话框中,如下所述添加新条目:

    1. 添加成员方框中输入用户、群组或服务帐号的电子邮件地址。

    2. 对于选择角色,请从列表中选择合适的 BigQuery 角色。如需详细了解分配给每个预定义 BigQuery 角色的权限,请参阅访问控制页面的角色部分。

    3. 点击添加

  5. 添加完或删除完访问权限控制后,点击完成

经典版界面

  1. 点击数据集右侧的下拉箭头并选择共享数据集

  2. 共享数据集对话框中,如下所述修改现有条目:

    • 要移除现有条目,请点击用户、群组、服务帐号右侧的 X 图标。
    • 要更改用户、群组或服务帐号的权限,请点击权限按钮并选择适当的访问权限级别:Is owner (OWNER)、Can edit (WRITER) 或 Can view (READER)。如需详细了解数据集级层的角色,请参阅数据集的初始角色
  3. 共享数据集对话框中,如下所述添加新条目:

    1. 点击添加人员字段左侧的下拉列表并选择适当的选项。

    2. 在文本框中输入一个值。例如,如果选择用户(使用电子邮件)(User by e-mail),则输入相应用户的电子邮件地址。

    3. 添加人员字段右侧,点击可以查看并从列表中选择适当的角色。

      向数据集添加人员

    4. 点击添加

  4. 完成添加、删除或修改访问权限控制后,点击保存更改

  5. 点击数据集右侧的下拉箭头并选择共享数据集,以验证访问权限控制。您可以在共享数据集对话框中确认相关设置。

命令行

  1. 使用 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

  2. 对 JSON 文件的 "access" 部分进行更改。您可以添加或移除任意 specialGroup 条目:projectOwnersprojectWritersprojectReadersallAuthenticatedUsers。还可以添加、移除或修改以下任一项:userByEmailgroupByEmaildomain

    例如,某个数据集的 JSON 文件的“访问权限”部分可能如下所示:

    {
     "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]"
      }
     ],
    }
    

  3. 修改完成后,使用 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

  4. 要验证访问权限控制的更改,请再次输入 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 参考文档

ds := client.Dataset(datasetID)
meta, err := ds.Metadata(ctx)
if err != nil {
	return err
}
// Append a new access control entry to the existing access list.
update := bigquery.DatasetMetadataToUpdate{
	Access: append(meta.Access, &bigquery.AccessEntry{
		Role:       bigquery.ReaderRole,
		EntityType: bigquery.UserEmailEntity,
		Entity:     "sample.bigquery.dev@gmail.com"},
	),
}

// Leverage the ETag for the update to assert there's been no modifications to the
// dataset since the metadata was originally read.
if _, err := ds.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

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

创建 Dataset.Builder 实例(方式是基于现有 Dataset 实例并使用 Dataset.toBuilder() 方法)。配置数据集开发工具对象。使用 Dataset.Builder.build() 方法构建更新的数据集,并调用 Dataset.update() 方法将更新发送到 API。

使用 Dataset.Builder.setAcl() 方法配置访问权限控制。

List<Acl> beforeAcls = dataset.getAcl();

// Make a copy of the ACLs so that they can be modified.
ArrayList<Acl> acls = new ArrayList<>(beforeAcls);
acls.add(Acl.of(new Acl.User("sample.bigquery.dev@gmail.com"), Acl.Role.READER));
DatasetInfo.Builder builder = dataset.toBuilder();
builder.setAcl(acls);

bigquery.update(builder.build());  // API request.

Python

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

使用数据集的访问权限控制设置 dataset.access_entries 属性,然后调用 client.update_dataset() 函数来更新属性。
from google.cloud import bigquery

# TODO(developer): 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)

entry = bigquery.AccessEntry(
    role="READER",
    entity_type="userByEmail",
    entity_id="sample.bigquery.dev@gmail.com",
)

entries = list(dataset.access_entries)
entries.append(entry)
dataset.access_entries = entries

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

full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
print(
    "Updated dataset '{}' with modified user permissions.".format(full_dataset_id)
)

后续步骤

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

发送以下问题的反馈:

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