本文档介绍了如何管理 BigQuery 中的表。您可以通过以下方式管理 BigQuery 表:
- 更新表的以下内容:
- 到期时间
- 说明
- 架构定义
- 标签
- 重命名(复制)表
- 复制表
- 删除表
- 恢复已删除的表
如需详细了解如何创建和使用表(包括获取表信息、列出表以及控制对表数据的访问),请参阅创建和使用表。
更新表属性
您可以更新表的以下元素:
所需权限
如需更新表,您至少必须具有 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。
- 使用 DDL
ALTER TABLE
语句。 - 使用
bq
命令行工具的bq update
命令。 - 调用
tables.patch
API 方法。 - 使用客户端库。
若要更新表的说明,请执行以下操作:
控制台
使用 Cloud Console 创建表时,您无法添加说明。创建表后,您可以在详细信息页面上添加说明。
在探索器面板中,展开您的项目和数据集,然后选择表。
在详细信息面板中,点击详细信息。
在说明部分,点击铅笔图标以修改说明。
在文本框中输入说明,然后点击更新进行保存。
SQL
借助数据定义语言 (DDL) 语句,您可以使用标准 SQL 查询语法创建和修改表和视图。
详细了解如何使用数据定义语言语句。
若要在 Cloud Console 中使用 DDL 语句更新表的说明,请执行以下操作:
点击编写新查询。
在查询编辑器文本区域中,输入您的 DDL 语句。
ALTER TABLE mydataset.mytable SET OPTIONS ( description="Description of mytable" )
点击运行。
bq
发出带 --description
标志的 bq update
命令。如果您要更新非默认项目中的表,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
bq update \ --description "description" \ project_id:dataset.table
替换以下内容:
description
:加英文引号的说明表的文本。project_id
:您的项目 IDdataset
:要更新的表所属数据集的名称table
:要更新的表的名称
示例:
输入以下命令,将 mydataset
中 mytable
的说明更改为“Description of mytable”。mydataset
属于默认项目。
bq update --description "Description of mytable" mydataset.mytable
输入以下命令,将 mydataset
中 mytable
的说明更改为“Description of mytable”。mydataset
属于 myotherproject
,而非默认项目。
bq update \
--description "Description of mytable" \
myotherproject:mydataset.mytable
API
调用 tables.patch
方法并使用表资源中的 description
属性来更新表的说明。由于 tables.update
方法会替换整个表资源,因此最好使用 tables.patch
方法。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
配置 Table.description 属性并调用 Client.update_table() 向 API 发送更新。
更新表的到期时间
您可以在数据集级层设置默认的表到期时间,也可以在创建表时设置表的到期时间。表的到期时间通常称为“存留时间”或 TTL。
如果在创建表时设置到期时间,则会忽略数据集的默认表到期时间。如果未在数据集级层设置默认的表到期时间,也未在创建表时设置表到期时间,则该表永不过期,您必须手动删除该表。
表创建完毕后,您可以随时通过以下方式更新表的到期时间:
- 使用 Cloud Console。
- 使用 DDL
ALTER TABLE
语句。 - 使用
bq
命令行工具的bq update
命令。 - 调用
tables.patch
API 方法。 - 使用客户端库。
如需更新表的到期时间,请执行以下操作:
控制台
使用 Cloud Console 创建表时,您无法添加到期时间。创建表后,您可以在表详细信息页面上添加或更新表过期时间。
在探索器面板中,展开您的项目和数据集,然后选择表。
在详细信息面板中,点击详细信息。
点击表信息旁边的铅笔图标
对于表过期时间,选择指定日期。然后使用下面的日历微件选择到期日期。
点击更新进行保存。已更新的到期时间会显示在表信息部分中。
SQL
借助数据定义语言 (DDL) 语句,您可以使用标准 SQL 查询语法创建和修改表和视图。
详细了解如何使用数据定义语言语句。
若要在 Cloud Console 中使用 DDL 语句更新到期时间,请执行以下操作:
点击编写新查询。
在查询编辑器文本区域中,输入您的 DDL 语句。
ALTER TABLE mydataset.mytable SET OPTIONS ( -- Sets table expiration to timestamp 2025-02-03 12:34:56 expiration_timestamp=TIMESTAMP "2025-02-03 12:34:56" )
点击运行。
bq
发出带 --expiration
标志的 bq update
命令。如果您要更新非默认项目中的表,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
bq update \
--expiration integer \
project_id:dataset.table
替换以下内容:
integer
:表的默认生命周期(以秒为单位)。最小值为 3600 秒(一小时)。过期时间以当前时间加上这个整数值为准。如果您指定0
,表过期时间将被移除,且表永不过期。您必须手动删除未设定过期时间的表。project_id
:您的项目 ID。dataset
:要更新的表所属数据集的名称。table
:要更新的表的名称。
示例:
输入以下命令可将 mydataset
中 mytable
的到期时间更新为 5 天(432000 秒)。mydataset
属于默认项目。
bq update --expiration 432000 mydataset.mytable
输入以下命令可将 mydataset
中 mytable
的到期时间更新为 5 天(432000 秒)。mydataset
属于 myotherproject
,而非默认项目。
bq update --expiration 432000 myotherproject:mydataset.mytable
API
调用 tables.patch
方法,并使用表资源中的 expirationTime
属性更新表过期时间(以毫秒为单位)。由于 tables.update
方法会替换整个表资源,因此最好使用 tables.patch
方法。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
配置 Table.expires 属性并调用 Client.update_table() 向 API 发送更新。
更新表的架构定义
如需详细了解如何更新表的架构定义,请参阅修改表架构。
重命名表
当前无法更改现有表的名称。如果需要更改表名称,请按照复制表的步骤进行操作。在复制操作中指定目标表时,请使用新的表名称。
复制表
您可以通过以下方式复制表:
- 使用 Cloud Console。
- 使用
bq
命令行工具的bq cp
命令。 - 调用 jobs.insert API 方法并配置
copy
作业 - 使用客户端库。
所需权限
若要复制表和分区,您必须至少具有以下权限。
对于源数据集:
bigquery.tables.get
bigquery.tables.getData
对于目标数据集:
bigquery.tables.create
:用于在目标数据集中创建表或分区的副本
以下预定义的 IAM 角色包含 bigquery.tables.create
、bigquery.tables.get
和 bigquery.tables.getData
权限:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
此外,若要运行复制作业,您必须具有 bigquery.jobs.create
权限。
以下预定义的 IAM 角色包含 bigquery.jobs.create
权限:
bigquery.user
bigquery.jobUser
bigquery.admin
此外,如果用户具有 bigquery.datasets.create
权限,则当该用户创建数据集时,系统会为其授予该数据集的 bigquery.dataOwner
访问权限。具备 bigquery.dataOwner
访问权限的用户可以复制该数据集中的表和分区,但如果目标数据集并非由该用户创建,则用户还需要具备对目标数据集的访问权限。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
复制表的限制
表的复制作业受到以下限制:
- 复制表时,目标表的名称必须遵循与创建表时相同的命名惯例。
- 表的副本需遵循 BigQuery 的有关复制作业的配额政策。
- 使用 Cloud Console 复制表时,不能覆盖目标数据集中的现有表。该表必须在目标数据集中具有唯一名称。
- 复制表时,目标数据集与要复制的表所属的源数据集必须位于同一位置。例如,您无法从欧盟的数据集复制表并将其写入美国境内的数据集。
- Cloud Console 不支持将多个源表复制到目标表。
- 使用 API 或
bq
命令行工具将多个源表复制到目标表时,所有源表的架构必须相同。 - 由于底层存储是动态管理的,因此 BigQuery 复制表所花费的时间可能因不同的运行而异。
复制单个源表
您可以通过以下方式复制单个表:
- 使用 Cloud Console。
- 使用
bq
命令行工具的bq cp
命令。 - 调用
jobs.insert
API 方法,配置一个copy
作业并指定sourceTable
属性。 - 使用客户端库。
在一个复制作业中,Cloud Console 仅支持一个源表和一个目标表。如需将多个源文件复制到目标表,必须使用 bq
命令行工具或 API。
如需复制单个源表,请执行以下操作:
控制台
bq
发出 bq cp
命令。可使用以下可选标志控制目标表的写入处置方式:
-a
或--append_table
用于将源表中的数据附加到目标数据集中的现有表。-f
或--force
会覆盖目标数据集中的现有表,并且不会提示您进行确认。-n
或--no_clobber
会在目标数据集中已存在同名表时返回以下错误消息:Table 'project_id:dataset.table' already exists, skipping.
。如果未指定-n
,则默认行为是提示您选择是否替换目标表。--destination_kms_key
是客户管理的 Cloud KMS 密钥,用于加密目标表。
本文未演示 --destination_kms_key
。如需了解详情,请参阅使用 Cloud Key Management Service 密钥保护数据。
如果源数据集或目标数据集属于非默认项目,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
(可选)提供 --location
标志并将其值设置为您的位置。
bq --location=location cp \ -a -f -n \project_id:dataset.source_table
\project_id:dataset.destination_table
请替换以下内容:
location
:您所在位置的名称。--location
是可选标志。例如,如果您在东京区域使用 BigQuery,可将该标志的值设置为asia-northeast1
。您可以使用.bigqueryrc
文件设置默认位置值。project_id
:您的项目 ID。dataset
:源数据集或目标数据集的名称。source_table
:要复制的表。destination_table
:目标数据集中表的名称。
示例:
输入以下命令可将 mydataset.mytable
复制到 mydataset2.mytable2
。两个数据集均属于默认项目。
bq cp mydataset.mytable mydataset2.mytable2
输入以下命令可复制 mydataset.mytable
并覆盖具有相同名称的目标表。源数据集属于默认项目。目标数据集属于 myotherproject
。-f
快捷键用于在无提示的情况下覆盖目标表。
bq cp -f \
mydataset.mytable \
myotherproject:myotherdataset.mytable
输入以下命令可复制 mydataset.mytable
并会在目标数据集中包含同名表时返回错误。源数据集属于默认项目。目标数据集属于 myotherproject
。-n
快捷键用于防止覆盖具有相同名称的表。
bq cp -n \
mydataset.mytable \
myotherproject:myotherdataset.mytable
输入以下命令可复制 mydataset.mytable
并向具有相同名称的目标表附加数据。源数据集属于默认项目。目标数据集属于 myotherproject
。-
a
快捷键用于附加到目标表。
bq cp -a mydataset.mytable myotherproject:myotherdataset.mytable
API
若要通过 API 复制现有的表,您可以调用 bigquery.jobs.insert
方法并配置一个 copy
作业。在作业资源的 jobReference
部分的 location
属性中指定您的位置。
您必须在作业配置中指定以下值:
"copy": { "sourceTable": { // Required "projectId": string, // Required "datasetId": string, // Required "tableId": string // Required }, "destinationTable": { // Required "projectId": string, // Required "datasetId": string, // Required "tableId": string // Required }, "createDisposition": string, // Optional "writeDisposition": string, // Optional },
其中,sourceTable
提供要复制的表的相关信息,destinationTable
提供新表的相关信息,createDisposition
指定是否在表不存在时创建表,writeDisposition
指定是覆盖还是附加到现有的表。
C#
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 BigQuery C# API 参考文档。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
PHP
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 BigQuery PHP API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
复制多个源表
您可以通过以下方式将多个源表复制到目标表:
- 使用
bq
命令行工具的bq cp
命令。 - 调用
jobs.insert
方法,配置一个copy
作业并指定sourceTables
属性。 - 使用客户端库。
所有源表必须具有相同架构,并且只能有一个目标表。
在指定源表时,您必须采用以英文逗号分隔的列表的形式。在复制多个源表时,您不能使用通配符。
如需复制多个源表,请执行以下操作:
控制台
目前,Cloud Console 不支持复制多个表。
bq
发出 bq cp
命令并采用英文逗号分隔列表的形式添加多个源表。可使用以下可选标志控制目标表的写入处置方式:
-a
或--append_table
用于将源表中的数据附加到目标数据集中的现有表。-f
或--force
用于覆盖目标数据集中的现有目标表,并且不会提示您进行确认。-n
或--no_clobber
会在目标数据集中已存在同名表时返回以下错误消息:Table 'project_id:dataset.table' already exists, skipping.
。如果未指定-n
,则默认行为是提示您选择是否替换目标表。--destination_kms_key
是客户管理的 Cloud Key Management Service 密钥,用于加密目标表。
本文未演示 --destination_kms_key
。如需了解详情,请参阅使用 Cloud Key Management Service 密钥保护数据。
如果源数据集或目标数据集属于非默认项目,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
(可选)提供 --location
标志并将其值设置为您的位置。
bq --location=location cp \ -a -f -n \project_id:dataset.source_table
,project_id:dataset.source_table
\project_id:dataset.destination_table
请替换以下内容:
location
:您所在位置的名称。--location
是可选标志。例如,如果您在东京区域使用 BigQuery,可将该标志的值设置为asia-northeast1
。您可以使用.bigqueryrc
文件设置默认位置值。project_id
:您的项目 ID。dataset
:源数据集或目标数据集的名称。source_table
:要复制的表。destination_table
:目标数据集中表的名称。
示例:
输入以下命令可将 mydataset.mytable
和 mydataset.mytable2
复制到 mydataset2.tablecopy
。所有数据集均属于默认项目。
bq cp \
mydataset.mytable,mydataset.mytable2 \
mydataset2.tablecopy
输入以下命令可将 mydataset.mytable
和 mydataset.mytable2
复制到 myotherdataset.mytable
并覆盖具有相同名称的目标表。目标数据集属于 myotherproject
,而非默认项目。-f
快捷键用于在无提示的情况下覆盖目标表。
bq cp -f \
mydataset.mytable,mydataset.mytable2 \
myotherproject:myotherdataset.mytable
输入以下命令可复制 myproject:mydataset.mytable
和 myproject:mydataset.mytable2
并会在目标数据集中包含同名表时返回错误。目标数据集属于 myotherproject
。-n
快捷键用于防止覆盖具有相同名称的表。
bq cp -n \
myproject:mydataset.mytable,myproject:mydataset.mytable2 \
myotherproject:myotherdataset.mytable
输入以下命令可复制 mydataset.mytable
和 mydataset.mytable2
并向具有相同名称的目标表附加数据。源数据集属于默认项目。目标数据集属于 myotherproject
。-a
快捷键用于附加到目标表。
bq cp -a \
mydataset.mytable,mydataset.mytable2 \
myotherproject:myotherdataset.mytable
API
如需使用 API 复制多个表,请调用 jobs.insert
方法,配置一个表 copy
作业,并指定 sourceTables
属性。
在作业资源的 jobReference
部分的 location
属性中指定您的区域。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
删除表
您可以通过以下方式删除表:
- 使用 Cloud Console。
- 使用
bq
命令行工具的bq rm
命令。 - 调用
tables.delete
API 方法。 - 使用客户端库。
目前,您每次只能删除一个表。
删除表时,该表中的所有数据也将一并删除。若要在指定的时间段后自动删除表,请设置数据集的默认表过期时间,或在创建表时设置到期时间。
所需权限
如需删除表,您至少必须具有 bigquery.tables.delete
和 bigquery.tables.get
权限。以下预定义的 IAM 角色包含 bigquery.tables.delete
和 bigquery.tables.get
权限:
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin
此外,如果用户具有 bigquery.datasets.create
权限,则当该用户创建数据集时,系统会为其授予该数据集的 bigquery.dataOwner
访问权限。具备 bigquery.dataOwner
访问权限的用户可以在数据集中删除表。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
删除表
如需删除表,请执行以下操作:
控制台
在探索器面板中,展开您的项目和数据集,然后选择表。
在详细信息面板中*,点击删除表。
在对话框中输入表的名称,然后点击删除以确认删除。
SQL
借助数据定义语言 (DDL) 语句,您可以使用标准 SQL 查询语法删除表。
详细了解如何使用数据定义语言语句。
如需在 Cloud Console 中使用 DDL 语句删除现有表,请按照以下步骤操作:
点击编写新查询。
在查询编辑器字段中,输入 DDL 语句。
DROP TABLE mydataset.mytable
点击运行。
bq
使用带有 --table
标志(或 -t
快捷方式)的 bq rm
命令删除表。使用 bq
命令行工具移除表时,必须确认该操作。您可以使用 --force
标志(或 -f
快捷方式)跳过确认。
如果该表属于非默认项目中的数据集,请按以下格式将相应项目 ID 添加到数据集名称中:project_id:dataset
。
bq rm \ -f \ -t \ project_id:dataset.table
替换以下内容:
project_id
:您的项目 IDdataset
:包含该表的数据集的名称table
:要删除的表的名称
示例:
输入以下命令可从 mydataset
删除 mytable
。mydataset
属于默认项目。
bq rm -t mydataset.mytable
输入以下命令可从 mydataset
删除 mytable
。mydataset
属于 myotherproject
,而非默认项目。
bq rm -t myotherproject:mydataset.mytable
输入以下命令可从 mydataset
删除 mytable
。mydataset
属于默认项目。该命令使用 -f
快捷方式绕过确认。
bq rm -f -t mydataset.mytable
API
调用 tables.delete
API 方法并使用 tableId
参数指定要删除的表。
C#
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 C# 设置说明进行操作。如需了解详情,请参阅 BigQuery C# API 参考文档。
Go
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Go 设置说明进行操作。如需了解详情,请参阅 BigQuery Go API 参考文档。
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
PHP
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 BigQuery PHP API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
Ruby
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Ruby 设置说明进行操作。如需了解详情,请参阅 BigQuery Ruby API 参考文档。
恢复已删除的表
表删除后的 7 天内,您可以恢复删除的表,包括显式删除和因表过期的隐式删除。7 天后,您将无法通过任何方法(包括打开支持服务工单)恢复删除的表。
您可以通过以下方式恢复已删除的表:
- 在
bq
命令行工具中使用@<time>
快照修饰器 - 使用客户端库
控制台
您无法使用 Cloud Console 恢复删除的表。
bq
如需恢复表,请将表复制操作与 @<time>
快照修饰器一起使用。首先,确定表存在时间的 UNIX 时间戳(以毫秒为单位)。然后,使用 bq copy
命令和快照修饰器。
例如,输入以下命令可将时间为 1418864998000
的 mydataset.mytable
复制到新表 mydataset.newtable
。
bq cp mydataset.mytable@1418864998000 mydataset.newtable
(可选)提供 --location
标志并将其值设置为您的位置。
您还可以指定相对偏移量。以下示例复制一小时前表的版本:
bq cp mydataset.mytable@-3600000 mydataset.newtable
如需了解详情,请参阅从某个时间点恢复表。
Go
Java
试用此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
Node.js
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 BigQuery Node.js API 参考文档。
Python
在尝试此示例之前,请按照《BigQuery 快速入门:使用客户端库》中的 Python 设置说明进行操作。如需了解详情,请参阅 BigQuery Python API 参考文档。
后续步骤
- 如需详细了解如何创建和使用表,请参阅创建和使用表。
- 如需详细了解如何处理数据,请参阅处理表数据。
- 如需详细了解如何指定表架构,请参阅指定架构。
- 如需详细了解如何修改表架构,请参阅修改表架构。
- 如需详细了解数据集,请参阅数据集简介。
- 如需详细了解视图,请参阅视图简介。