从 Datastore 导出文件中加载数据

BigQuery 支持从使用 Datastore 托管式导入和导出服务创建的 Datastore 导出文件中加载数据。您可以使用托管式导入和导出服务将 Datastore 实体导出到 Cloud Storage 存储分区，然后再将导出文件以表的形式加载到 BigQuery 中。

要了解如何创建 Datastore 导出文件，请参阅 Datastore 文档中的导出和导入实体部分。如需了解如何安排导出，请参阅安排导出。

注意：要将 Datastore 导出文件加载到 BigQuery，您必须在导出命令中指定实体过滤条件。如果在未指定实体过滤条件的情况下导出了数据，则这些数据无法加载到 BigQuery 中。

通过在 API 中设置 projectionFields 属性或在 bq 命令行工具中使用 --projection_fields 标志，您可以控制 BigQuery 应加载哪些属性。

如果您希望跳过加载过程，则可以将导出文件设置为一个外部数据源，从而直接查询该导出文件。如需了解详情，请参阅外部数据源。

如果要将 Cloud Storage 中的数据加载到 BigQuery 表中，则包含该表的数据集必须与 Cloud Storage 存储桶位于同一区域或多区域中。

限制

当您将 Datastore 导出文件中的数据加载到 BigQuery 中时，请注意以下限制：

• 指定 Datastore 导出文件时，不得在 Cloud Storage URI 中使用通配符。
• 从 Datastore 导出文件中加载数据时，只能指定一个 Cloud Storage URI。
• 不得在已定义架构的现有表中附加 Datastore 导出数据。
• 为了顺利加载 Datastore 导出数据，导出数据中的实体必须共用一个其独特属性名称数量小于 10000 的一致架构。
• 如果在未指定实体过滤条件的情况下导出了数据，则这些数据无法加载到 BigQuery 中。导出请求的实体过滤条件中必须包含一个或多个种类名称。
• Datastore 导出文件的字段大小上限为 64 KB。加载 Datastore 导出文件时，任何大小超过 64 KB 的字段都会被截断。

准备工作

授予为用户提供执行本文档中的每个任务所需权限的 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)

您也可以使用自定义角色或其他预定义角色来获取这些权限。

加载 Datastore 导出服务数据

如需从 Datastore 导出元数据文件中加载数据，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器窗格中，展开您的项目，然后选择数据集。
3. 在数据集信息部分中，点击 创建表。
4. 在创建表面板中，指定以下详细信息：
1. 在来源部分中，从基于以下数据源创建表列表中选择 Google Cloud Storage。之后，执行以下操作：
   1. 从 Cloud Storage 存储桶中选择一个文件，或输入 Cloud Storage URI。您无法在 Google Cloud 控制台中添加多个 URI，但支持使用通配符。Cloud Storage 存储桶必须与您要创建、附加或覆盖的表所属的数据集位于同一位置。
      Datastore 导出文件的 URI 必须以 KIND_NAME.export_metadata 或 export[NUM].export_metadata 结尾。例如，在 default_namespace_kind_Book.export_metadata 中，Book 是种类名称，default_namespace_kind_Book 是由 Datastore 生成的文件名。
   2. 在文件格式部分，选择 Cloud Datastore 备份。
2. 在目标部分，指定以下详细信息：
   1. 在数据集部分，选择您要在其中创建表的数据集。
   2. 在表字段中，输入您要创建的表的名称。
   3. 确认表类型字段是否设置为原生表。
3. 在架构部分中，无需执行任何操作。系统会推断 Datastore 导出文件的架构。
4. 可选：指定分区和聚簇设置。如需了解详情，请参阅创建分区表和创建和使用聚簇表。
5. 点击高级选项，然后执行以下操作：
   • 在写入偏好设置部分，选中只写入空白表。此选项创建一个新表并向其中加载数据。
   • 如果要忽略表架构中不存在的行中的值，请选择未知值。
   • 在加密部分，点击客户管理的密钥，以使用 Cloud Key Management Service 密钥。如果保留 Google 管理的密钥设置，BigQuery 将对静态数据进行加密。
   如需了解可用选项，请参阅 Datastore 选项。
6. 点击创建表。

bq

使用 bq load 命令并将 source_format 设置为 DATASTORE_BACKUP。添加 --location 标志并将其值设置为您的位置。

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

请替换以下内容：

• LOCATION：您所在的位置。--location 是可选标志。例如，如果您在东京地区使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置默认位置值。
• FORMAT：DATASTORE_BACKUP。
• DATASET：您要向其中加载数据的表所属的数据集。
• TABLE：要向其中加载数据的表。如果该表不存在，系统会创建一个。
• PATH_TO_SOURCE：Cloud Storage URI。

例如，以下命令会将 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Datastore 导出文件加载到名为 book_data 的表中。 mybucket 和 mydataset 是在 US 多区域位置创建的。

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

设置以下属性可使用 API 加载 Datastore 导出数据。

1. 创建指向 Cloud Storage 中源数据的加载作业。

2. 在作业资源 jobReference 部分的 location 属性中指定您的位置。

3. 源 URI 必须是完全限定的，格式为 gs://[BUCKET]/[OBJECT]。文件（对象）名必须以 [KIND_NAME].export_metadata 结尾。Datastore 导出文件只能使用一个 URI，且不得使用通配符。

4. 将 JobConfigurationLoad.sourceFormat 属性设置为 DATASTORE_BACKUP，以指定数据格式。

使用 Datastore 数据覆盖或附加到表

将 Datastore 导出数据加载到 BigQuery 时，您可以创建新表来存储数据，也可以覆盖现有表。但您无法将 Datastore 导出数据附加到现有表。

如果您试图将 Datastore 导出数据附加到现有表中，则会看到以下错误结果：Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table。

要使用 Datastore 导出数据覆盖现有表，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在浏览器窗格中，展开您的项目，然后选择数据集。
3. 在数据集信息部分中，点击 创建表。
4. 在创建表面板中，指定以下详细信息：
1. 在来源部分中，从基于以下数据源创建表列表中选择 Google Cloud Storage。之后，执行以下操作：
   1. 从 Cloud Storage 存储桶中选择一个文件，或输入 Cloud Storage URI。您无法在 Google Cloud 控制台中添加多个 URI，但支持使用通配符。Cloud Storage 存储桶必须与您要创建、附加或覆盖的表所属的数据集位于同一位置。
      Datastore 导出文件的 URI 必须以 KIND_NAME.export_metadata 或 export[NUM].export_metadata 结尾。例如，在 default_namespace_kind_Book.export_metadata 中，Book 是种类名称，default_namespace_kind_Book 是由 Datastore 生成的文件名。
   2. 在文件格式部分，选择 Cloud Datastore 备份。
注意：您可以在向表附加数据或覆盖其数据时修改表的架构。如需详细了解加载操作期间支持的架构更改，请参阅修改表架构。
2. 在目标部分，指定以下详细信息：
   1. 在数据集部分，选择您要在其中创建表的数据集。
   2. 在表字段中，输入您要创建的表的名称。
   3. 确认表类型字段是否设置为原生表。
3. 在架构部分中，无需执行任何操作。系统会推断 Datastore 导出文件的架构。
注意：您可以在向表附加数据或覆盖其数据时修改表的架构。如需详细了解加载操作期间支持的架构更改，请参阅修改表架构。
4. 可选：指定分区和聚簇设置。如需了解详情，请参阅创建分区表和创建和使用聚簇表。 您无法通过附加或覆盖表将表转换为分区表或聚簇表。Google Cloud 控制台不支持在加载作业中对分区表或聚簇表执行附加或覆盖操作。
5. 点击高级选项，然后执行以下操作：
   • 在写入偏好设置部分，选择附加到表或覆盖表。
   • 如果要忽略表架构中不存在的行中的值，请选择未知值。
   • 在加密部分，点击客户管理的密钥，以使用 Cloud Key Management Service 密钥。如果保留 Google 管理的密钥设置，BigQuery 将对静态数据进行加密。
   如需了解可用选项，请参阅 Datastore 选项。
6. 点击创建表。

bq

使用带有 --replace 标志的 bq load 命令，并将 source_format 设置为 DATASTORE_BACKUP。添加 --location 标志并将其值设置为您的位置。

bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE

请替换以下内容：

• LOCATION：您所在的位置。--location 是可选标志。例如，如果您在东京地区使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置默认位置值。
• FORMAT：DATASTORE_BACKUP。
• DATASET：包含要向其中加载数据的表的数据集。
• TABLE：要覆盖的表。
• PATH_TO_SOURCE：Cloud Storage URI。

例如，以下命令会加载 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Datastore 导出文件，并覆盖名为 book_data 的表：

bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

设置以下属性可通过 API 加载数据。

1. 创建指向 Cloud Storage 中源数据的加载作业。

2. 在作业资源 jobReference 部分的 location 属性中指定您的位置。

3. 源 URI 必须是完全限定的，格式为 gs://[BUCKET]/[OBJECT]。文件（对象）名必须以 [KIND_NAME].export_metadata 结尾。Datastore 导出文件只能使用一个 URI，且不得使用通配符。

4. 将 JobConfigurationLoad.sourceFormat 属性设置为 DATASTORE_BACKUP，以指定数据格式。

5. 将 JobConfigurationLoad.writeDisposition 属性设置为 WRITE_TRUNCATE，以指定写入处置方式。

Datastore 选项

如需更改 BigQuery 解析 Datastore 导出数据的方式，请指定以下选项：

控制台选项	bq 工具标志	BigQuery API 属性	说明
不可用	--projection_fields	projectionFields	逗号分隔列表，用于指示要从 Datastore 导出文件加载到 BigQuery 中的实体属性。属性名称区分大小写，且必须是顶级属性。如果没有指定属性，BigQuery 将加载所有属性。如果系统在 Datastore 导出文件中找不到任何指定属性，则会在作业结果中返回一个无效错误。默认值为 ''。

数据类型转换

BigQuery 会将 Datastore 导出文件中每个实体的数据转换为 BigQuery 数据类型。 下表介绍了不同数据类型之间的转换。

Datastore 数据类型	BigQuery 数据类型
数组	ARRAY
Blob	BYTES
布尔值	BOOLEAN
日期和时间	TIMESTAMP
嵌入式实体	RECORD
浮点数	FLOAT
地理位置点	RECORD [{"lat","DOUBLE"}, {"long","DOUBLE"}]
整数	INTEGER
键	RECORD
Null	STRING
文本字符串	STRING（截断为 64 KB）

Datastore 键属性

Datastore 中的每个实体都有一个唯一键，其中包含命名空间和路径等信息。BigQuery 会为键创建 RECORD 数据类型，每条信息都具有嵌套字段，如下表所述。

键属性	说明	BigQuery 数据类型
__key__.app	Datastore 应用名称。	STRING
__key__.id	实体的 ID，或 null（如果设置了 __key__.name）。	INTEGER
__key__.kind	实体的种类。	STRING
__key__.name	实体的名称，或 null（如果设置了 __key__.id）。	STRING
__key__.namespace	如果 Datastore 应用使用自定义命名空间，该属性即为实体的命名空间。否则，会以空字符串表示默认命名空间。	STRING
__key__.path	经过拼合的祖先实体路径，其中包含从根实体到实体本身的“种类-标识符”对序列。例如："Country", "USA", "PostalCode", 10011, "Route", 1234。	STRING