批量加载数据
您可以将 Cloud Storage 中的数据或本地文件作为批量操作加载到 BigQuery 中。源数据可以采用以下任一格式:
- Avro
- 英文逗号分隔值 (CSV)
- JSON(以换行符分隔)
- ORC
- Parquet
- 存储在 Cloud Storage 中的 Datastore 导出文件。
- 存储在 Cloud Storage 中的 Firestore 导出文件
您还可以使用 BigQuery Data Transfer Service 设置从 Cloud Storage 到 BigQuery 的周期性加载作业。
准备工作
授予为用户提供执行本文档中的每个任务所需权限的 Identity and Access Management (IAM) 角色,并创建一个数据集来存储您的数据。
所需权限
如需将数据加载到 BigQuery,您需要拥有 IAM 权限才能运行加载作业以及将数据加载到 BigQuery 表和分区中。如果要从 Cloud Storage 加载数据,您还需要拥有访问包含数据的存储桶的 IAM 权限。
将数据加载到 BigQuery 的权限
如需将数据加载到新的 BigQuery 表或分区中,或者附加或覆盖现有的表或分区,您需要拥有以下 IAM 权限:
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
以下预定义 IAM 角色都具有将数据加载到 BigQuery 表或分区所需的权限:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(包括bigquery.jobs.create
权限)bigquery.user
(包括bigquery.jobs.create
权限)bigquery.jobUser
(包括bigquery.jobs.create
权限)
此外,如果您拥有 bigquery.datasets.create
权限,则可以在自己创建的数据集中使用加载作业创建和更新表。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
从 Cloud Storage 加载数据的权限
如需获得从 Cloud Storage 存储桶加载数据所需的权限,请让您的管理员为您授予存储桶的 Storage Admin (roles/storage.admin
) IAM 角色。如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色可提供从 Cloud Storage 存储桶加载数据所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需从 Cloud Storage 存储桶加载数据,您需要具备以下权限:
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
创建数据集
创建 BigQuery 数据集来存储数据。
从 Cloud Storage 加载数据
BigQuery 支持从以下任意一种 Cloud Storage 存储类别加载数据:
- Standard
- Nearline
- Coldline
- 归档
如需了解如何将数据加载到 BigQuery 中,请参阅数据格式页面:
如需了解如何配置从 Cloud Storage 到 BigQuery 的周期性负载,请参阅 Cloud Storage 转移作业。
位置注意事项
您无法在创建数据集后更改其位置,但可以复制数据集或手动移动数据集。如需了解详情,请参阅:
检索 Cloud Storage URI
要从 Cloud Storage 数据源加载数据,您必须提供 Cloud Storage URI。
Cloud Storage 资源路径包含存储桶名称和对象(文件名)。例如,如果 Cloud Storage 存储桶的名称为 mybucket
,且数据文件的名称为 myfile.csv
,则资源路径为 gs://mybucket/myfile.csv
。
BigQuery 不支持 Cloud Storage 资源路径在初始双斜杠之后添加多个连续斜杠。Cloud Storage 对象名称可包含多个连续斜杠(“/”)字符。但是,BigQuery 会将多个连续斜杠转换为单个斜杠。例如,虽然以下资源路径在 Cloud Storage 中有效,但在 BigQuery 中无效:gs://bucket/my//object//name
。
如需检索 Cloud Storage 资源路径,请执行以下操作:
打开 Cloud Storage 控制台
浏览到包含源数据的对象(文件)所在的位置。
点击对象的名称。
对象详情页面随即会打开。
复制 gsutil URI 字段中提供的值,该值以
gs://
开头。
Google Datastore 导出文件只能指定一个 URI,且必须以 .backup_info
或 .export_metadata
结尾。
Cloud Storage URI 的通配符支持
如果您的数据分为多个文件,则可以使用星号 (*) 通配符选择多个文件。使用星号通配符必须遵循以下规则:
- 星号可以出现在对象名称内或对象名称末尾。
- 不支持使用多个星号。例如,路径
gs://mybucket/fed-*/temp/*.csv
无效。 - 不支持在存储桶名称中使用星号。
示例:
以下示例展示了如何选择以前缀
gs://mybucket/fed-samples/fed-sample
开头的所有文件夹中的所有文件:gs://mybucket/fed-samples/fed-sample*
以下示例展示了如何仅选择名为
fed-samples
的文件夹中和fed-samples
的任何子文件夹中扩展名为.csv
的文件:gs://mybucket/fed-samples/*.csv
以下示例展示了如何选择文件夹
fed-samples
中命名格式为fed-sample*.csv
的文件。此示例不会选择fed-samples
子文件夹中的文件。gs://mybucket/fed-samples/fed-sample*.csv
使用 bq 命令行工具时,您可能需要在某些平台上对星号进行转义。
从 Cloud Storage 加载 Datastore 或 Firestore 导出数据时,不能使用星号通配符。
限制
将数据从 Cloud Storage 存储桶加载到 BigQuery 时,需要遵循以下限制:
- BigQuery 不保证外部数据源的数据一致性。在查询运行的过程中,底层数据的更改可能会导致意外行为。
- BigQuery 不支持 Cloud Storage 对象版本控制。如果您在 Cloud Storage URI 中添加了世代编号,则加载作业将失败。
Cloud Storage 源数据可能还存在其他限制,具体取决于源数据的格式。如需了解详情,请参阅:
从本地文件加载数据
您可以使用以下方式之一从可读数据源(如本地机器)加载数据:
- Trusted Cloud 控制台
- bq 命令行工具的
bq load
命令 - API
- 客户端库
使用 Trusted Cloud 控制台或 bq 命令行工具加载数据时,系统会自动创建加载作业。
如需从本地数据源加载数据,请按如下所述操作:
控制台
在 Trusted Cloud 控制台中打开 BigQuery 页面。
在浏览器面板中,展开您的项目并选择数据集。
展开
操作选项,然后点击打开。在详情面板中,点击创建表
。在创建表页面的来源部分,执行以下操作:
- 在基于以下数据创建表部分,选择上传。
- 在选择文件部分,点击浏览。
- 浏览到相应文件,然后点击打开。请注意,本地文件不支持使用通配符和逗号分隔列表。
- 在文件格式部分,选择 CSV、JSON(以换行符分隔)、Avro、Parquet 或 ORC。
在创建表页面的目标部分,执行以下操作:
- 在项目部分,选择相应的项目。
- 在数据集部分,选择相应的数据集。
- 在表字段中,输入您要在 BigQuery 中创建的表的名称。
- 确认 Table type 设置为 Native table。
在架构部分中,输入架构定义。
对于 CSV 和 JSON 文件,您可以勾选自动检测选项来启用架构自动检测功能。对于其他支持的文件类型,架构信息在源数据中为自描述形式。
您也可按照以下方式手动输入架构信息:
点击以文本形式修改,并以 JSON 数组格式输入表架构:
使用添加字段手动输入架构。
可选:在高级选项中,选择写入处置方式:
- 只写入空白表:仅当表为空时才写入数据。
- 附加到表:将数据附加到表的末尾。这是默认设置。
- 覆盖表:在写入新数据之前清空表中的所有现有数据。
点击创建表。
bq
使用 bq load
命令,指定 source_format
,并添加本地文件的路径。
(可选)提供 --location
标志并将其值设置为您的位置。
如果要在非默认项目中加载数据,请按照以下格式将项目 ID 添加到数据集:PROJECT_ID:DATASET
。
bq --location=LOCATION load \ --source_format=FORMAT \ PROJECT_ID:DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
替换以下内容:
LOCATION
:您所在的位置。--location
是可选标志。例如,如果您在东京区域使用 BigQuery,请将该标志的值设置为asia-northeast1
。您可以使用 .bigqueryrc 文件设置位置的默认值。FORMAT
:CSV
、AVRO
、PARQUET
、ORC
或NEWLINE_DELIMITED_JSON
。project_id
:您的项目 ID。dataset
:现有数据集。table
:要向其中加载数据的表的名称。path_to_source
:本地文件的路径。schema
:有效架构。该架构可以是本地 JSON 文件,也可以在命令中以内嵌形式输入架构。您还可以改用--autodetect
标志,而无需提供架构定义。
此外,您可以为选项添加标志,以便控制 BigQuery 解析数据的方式。例如,您可以使用 --skip_leading_rows
标志来忽略 CSV 文件中的标题行。如需了解详情,请参阅 CSV 选项和 JSON 选项。
示例:
以下命令将本地以换行符分隔的 JSON 文件 (mydata.json
) 加载到默认项目的 mydataset
内名为 mytable
的表中。架构是在名为 myschema.json
的本地架构文件中定义的。
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
以下命令将本地 CSV 文件 (mydata.csv
) 加载到 myotherproject
项目的 mydataset
内名为 mytable
的表中。架构采用以下格式以内嵌方式定义:FIELD:DATA_TYPE, FIELD:DATA_TYPE
。
bq load \
--source_format=CSV \
myotherproject:mydataset.mytable \
./mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
以下命令将本地 CSV 文件 (mydata.csv
) 加载到默认项目的 mydataset
内名为 mytable
的表中。架构是使用架构自动检测功能定义的。
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
./mydata.csv
C#
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 C# 设置说明进行操作。 如需了解详情,请参阅 BigQuery C# API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
在运行代码示例之前,请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN
环境变量设置为 s3nsapis.fr
。
UploadCsvOptions
。
Go
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Go 设置说明进行操作。 如需了解详情,请参阅 BigQuery Go API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
在运行代码示例之前,请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN
环境变量设置为 s3nsapis.fr
。
NewReaderSource
的 DataFormat 属性设置为相应的格式。
Java
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
在运行代码示例之前,请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN
环境变量设置为 s3nsapis.fr
。
Node.js
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情,请参阅 BigQuery Node.js API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
在运行代码示例之前,请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN
环境变量设置为 s3nsapis.fr
。
metadata
参数设置为相应的格式。
PHP
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 PHP 设置说明进行操作。 如需了解详情,请参阅 BigQuery PHP API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
在运行代码示例之前,请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN
环境变量设置为 s3nsapis.fr
。
Python
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Python 设置说明进行操作。 如需了解详情,请参阅 BigQuery Python API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
在运行代码示例之前,请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN
环境变量设置为 s3nsapis.fr
。
Ruby
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 BigQuery Ruby API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
在运行代码示例之前,请将 GOOGLE_CLOUD_UNIVERSE_DOMAIN
环境变量设置为 s3nsapis.fr
。
format
参数设置为相应的格式。
限制
从本地数据源加载数据会受到以下限制:
- 从本地数据源加载文件时,不支持使用通配符和英文逗号分隔列表。各文件必须分别加载。
- 使用 Trusted Cloud 控制台时,从本地数据源加载的文件不能超过 10 MB。对于超过此大小的文件,请从 Cloud Storage 加载文件。
加载作业容量
与查询的按需模式类似,加载作业默认使用共享槽池。BigQuery 并不保证此共享池的可用容量,也不保证加载作业吞吐量。
如需提高吞吐量或可预测地控制加载作业的容量,您可以创建槽预留并分配专用的 PIPELINE
槽来运行加载作业。如需了解详情,请参阅预留分配。
加载经过压缩和未经压缩的数据
对于 Avro、Parquet 和 ORC 格式,BigQuery 支持加载其中的文件数据已使用受支持的编解码器压缩的文件。但是,BigQuery 不支持加载采用这些格式但本身已压缩的文件(例如,使用 gzip
实用程序)。
加载压缩数据和未压缩数据时,首选格式都是 Avro 二进制格式。Avro 数据加载速度更快,因为可以并行读取数据,即使数据块已经过压缩也是如此。 如需查看受支持的压缩编解码器的列表,请参阅 Avro 压缩。
Parquet 二进制格式也是一个不错的选择,因为 Parquet 可高效地逐列进行编码,这通常会改善压缩比并减小文件大小。Parquet 文件还可利用支持并行加载文件的压缩方法。 如需查看受支持的压缩编解码器的列表,请参阅 Parquet 压缩。
ORC 二进制格式的优势与 Parquet 格式相类似。ORC 文件中的数据加载速度很快,因为可以并行读取数据条带。每个数据条带中的行将按顺序加载。为了优化加载时间,建议使用大小约为 256 MB 或更小的数据条带。 如需查看受支持的压缩编解码器的列表,请参阅 ORC 压缩。
对于其他数据格式(如 CSV 和 JSON),BigQuery 加载未压缩文件的速度要比加载压缩文件快得多,因为可以并行读取未压缩文件。由于未经压缩的文件较大,因此使用这些文件可能会超出带宽限制,并且数据在加载到 BigQuery 之前会产生较高的 Cloud Storage 暂存费用。请注意,无论文件是否已经过压缩,都无法保证行的排序。您需要根据具体用例来权衡这些利弊,这一点很重要。
一般来说,如果带宽有限,建议先使用 gzip
压缩 CSV 和 JSON 文件,然后再上传到 Cloud Storage。在将数据加载到 BigQuery 时,gzip
是 CSV 和 JSON 文件唯一支持的文件压缩类型。如果对您的应用来说加载速度很重要,并且您有足够的带宽来加载数据,请保留文件的未压缩状态。
对表执行附加或覆盖操作
您可以通过源文件或附加查询结果,将其他数据加载到表中。如果数据架构与目标表或分区的架构不匹配,您可以在执行附加或覆盖操作时更新架构。
如果您要在附加数据时更新架构,BigQuery 将允许执行以下操作:
- 添加新字段
- 将
REQUIRED
字段放宽为NULLABLE
如果您要覆盖表,则架构始终会被覆盖。在覆盖表时,架构更新不受限制。
在 Trusted Cloud 控制台中,使用写入偏好设置选项指定从源文件或查询结果加载数据时要执行的操作。bq 命令行工具和 API 包括以下选项:
控制台选项 | bq 工具标志 | BigQuery API 属性 | 说明 |
---|---|---|---|
只写入空白表 | 无 | WRITE_EMPTY | 仅当表为空时才写入数据。 |
附加到表 | --noreplace 或 --replace=false ;如果未指定 --replace ,则默认为附加 |
WRITE_APPEND | (默认)在表末尾附加数据。 |
覆盖表 | --replace 或 --replace=true |
WRITE_TRUNCATE | 清空表中所有现有数据然后再写入新数据。 |
配额政策
如需了解批量加载数据的配额政策,请参阅“配额和限制”页面中的加载作业。
查看当前配额用量
您可以运行 INFORMATION_SCHEMA
查询来查看在指定时间段内运行的作业的元数据,从而查看查询、加载、提取或复制作业的当前使用情况。您可以将当前用量与配额限制进行比较,以确定特定类型的作业的配额用量。以下示例查询使用 INFORMATION_SCHEMA.JOBS
视图按项目列出查询、加载、提取和复制作业的数量:
SELECT sum(case when job_type="QUERY" then 1 else 0 end) as QRY_CNT, sum(case when job_type="LOAD" then 1 else 0 end) as LOAD_CNT, sum(case when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT, sum(case when job_type="COPY" then 1 else 0 end) as CPY_CNT FROM `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT WHERE date(creation_time)= CURRENT_DATE()
价格
使用共享槽池将数据批量加载到 BigQuery 无需付费。如需了解详情,请参阅 BigQuery 数据提取价格。
用例示例
假设有一个夜间批处理流水线,需要在固定的截止时间之前完成。在此截止时间之前,需要获取数据以供其他批处理进一步处理,从而生成要发送到监管机构的报告。此用例在金融等受监管的行业中很常见。
使用加载作业批量加载数据是此用例的正确方法,因为如果可以满足截止时间要求,就可以不必担心延迟时间。确保 Cloud Storage 存储桶满足将数据加载到 BigQuery 数据集中的位置要求。
BigQuery 加载作业的结果是原子化的;要么已插入所有记录,要么不插入任何记录。最佳实践是在单个加载作业中插入所有数据时,使用 JobConfigurationLoad
资源的 WRITE_TRUNCATE
处置方式创建新表。这一点在重试失败的加载作业时非常重要,因为客户端可能无法区分失败的作业和由于将成功状态传回客户端等原因而导致的失败情况。
假设要注入的数据已成功复制到 Cloud Storage,使用指数退避算法进行重试足以解决注入故障。
建议夜间批量作业不要达到默认配额(每个表每天加载 1,500 次),即使重试也是如此。以增量方式加载数据时,默认配额足以每 5 分钟运行一次加载作业,并且平均每项作业有至少 1 次重试未使用配额。