从 Datastore 导出文件中加载数据

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

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

通过在 API 中设置 projectionFields 或在命令行界面中使用 --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 的字段都会被截断。

所需权限

在将数据加载到 BigQuery 时,您需要拥有相关权限,才能运行加载作业并将数据加载到新的或现有的 BigQuery 表和分区中。如果要从 Cloud Storage 加载数据,您还需要拥有对您的数据所在的存储分区的访问权限。

BigQuery 权限

至少需具备以下权限,才能将数据加载到 BigQuery。无论您是要将数据加载到新的表或分区,还是要附加到或覆盖现有的表或分区,都必须具备这些权限。

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

以下预定义的 IAM 角色同时具有 bigquery.tables.createbigquery.tables.updateData 权限:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

以下预定义的 IAM 角色具有 bigquery.jobs.create 权限:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

此外,如果用户具有 bigquery.datasets.create 权限,则当该用户创建数据集时,系统会为其授予该数据集的 bigquery.dataOwner 访问权限。借助 bigquery.dataOwner 访问权限,用户可以通过使用加载作业在数据集中创建和更新表。

如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅访问控制

Cloud Storage 权限

如需从 Cloud Storage 存储分区中加载数据,您必须获得 storage.objects.get 权限。如果要使用 URI 通配符,您还必须具有 storage.objects.list 权限。

授予预定义的 IAM 角色 storage.objectViewer,即可同时提供 storage.objects.getstorage.objects.list 权限。

加载 Datastore 导出服务数据

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

控制台

  1. 在 Cloud Console 中打开 BigQuery 网页界面。

    转到 BigQuery 网页界面

  2. 在导航面板的资源部分中,展开您的 Google Cloud 项目并选择数据集。点击创建表。加载数据的过程与创建空表的过程相同。

    创建表。

  3. 创建表页面的来源部分,执行以下操作:

    • 基于以下来源创建表部分,选择 Cloud Storage
    • 在来源字段中,输入 Cloud Storage URI。Cloud Storage 存储分区必须与您要创建的表所属的数据集位于同一位置。Datastore 导出文件的 URI 应以 [KIND_NAME].export_metadataexport[NUM].export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是种类名称,default_namespace_kind_Book 是由 Datastore 生成的文件名。
    • 对于文件格式,请选择 Datastore 备份 (Datastore Backup)
  4. 创建表页面的目标部分,执行以下操作:

    • 数据集名称部分,选择相应数据集。

      选择数据集。

    • 表名称字段中,输入您要在 BigQuery 中创建的表的名称。

    • 验证表类型是否设置为原生表

  5. 架构部分中,无需执行任何操作。系统会根据 Datastore 导出文件推断架构。

  6. 高级选项部分中选择适用项,然后点击创建表。如需了解可用选项,请参阅 Datastore 选项

经典版界面

  1. 转到经典版 BigQuery 网页界面。
    转到 BigQuery 网页界面
  2. 在导航面板中,将鼠标悬停在数据集上,点击向下箭头图标 向下箭头图标。,然后点击 Create new table。加载数据的过程与创建空表的过程相同。
  3. Create Table 页面的 Source Data 部分,执行以下操作:
    • Create from source 保持选中状态。
    • 对于 Location,选择 Cloud Storage,然后在来源字段中输入 Cloud Storage URI。Cloud Storage 存储分区必须与您要创建的表所属的数据集位于同一位置。Datastore 导出文件的 URI 应以 [KIND_NAME].export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是种类名称,default_namespace_kind_Book 是由 Datastore 生成的文件名。

      请验证是否已在 Cloud Storage URI 中指定 [KIND_NAME]。如果指定的 URI 中不含 [KIND_NAME],您会收到以下错误:does not contain valid backup metadata. (error code: invalid)

    • 对于 File format,请选择 Datastore Backup
  4. Create Table 页面的 Destination Table 部分,执行以下操作:
    • 对于 Table name,选择适当的数据集,然后在表名称字段中输入要在 BigQuery 中创建的表的名称。
    • 验证 Table type 是否设为 Native table
  5. 架构部分中,无需执行任何操作。系统会根据 Datastore 导出文件推断架构。
  6. Options 部分中选择适用项,然后点击 Create Table。如需了解可用选项,请参阅 Datastore 选项

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 文件设置默认位置值。
  • FORMATDATASTORE_BACKUP
  • DATASET:您要向其中加载数据的表所属的数据集。
  • TABLE:要向其中加载数据的表。如果该表不存在,系统会创建一个。
  • PATH_TO_SOURCECloud Storage URI

例如,以下命令会将 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Datastore 导出文件加载到名为 book_data 的表中。 mybucketmydataset 是在 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. configuration.load.sourceFormat 属性设置为 DATASTORE_BACKUP,以指定数据格式。

Datastore Admin 备份

如果您使用 Datastore 管理员备份功能导出您的 Datastore 数据,请注意文件扩展名应为 .backup_info,而非 .export_metadata。将数据导入 BigQuery 时,您可以使用 .backup_info 文件或 .export_metadata 文件,直到 Datastore 管理员备份服务不再可用。

使用 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. 在 Cloud Console 中打开 BigQuery 网页界面。转到 BigQuery 网页界面
  2. 在导航面板的资源部分中,展开您的 Cloud 项目并选择数据集。点击创建表。加载数据的过程与创建空表的过程相同。创建表。
  3. 创建表页面的来源部分,执行以下操作:

    • 基于以下来源创建表部分,选择 Cloud Storage

    • 在来源字段中,输入 Cloud Storage URI。Cloud Storage 存储分区必须与您要创建的表所属的数据集位于同一位置。Datastore 导出文件的 URI 应以 [KIND_NAME].export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是种类名称,default_namespace_kind_Book 是由 Datastore 生成的文件名。

      请验证是否已在 Cloud Storage URI 中指定 [KIND_NAME]。如果指定的 URI 中不含 [KIND_NAME],您会收到以下错误:does not contain valid backup metadata. (error code: invalid)

    • 对于文件格式,请选择 Datastore 备份 (Datastore Backup)

  4. 创建表页面的目标部分,执行以下操作:

    • 数据集名称部分,选择相应数据集。

      选择数据集。

    • 表名称字段中,输入您要在 BigQuery 中创建的表的名称。

    • 验证表类型是否设置为原生表

  5. 架构部分中,无需执行任何操作。系统会根据 Datastore 导出文件推断架构。

  6. 对于高级选项部分的写入偏好设置,选择覆盖表

  7. 点击创建表

经典版界面

  1. 转到经典版 BigQuery 网页界面。
    转到 BigQuery 网页界面
  2. 在导航面板中,将鼠标悬停在数据集上,点击向下箭头图标 向下箭头图标。,然后点击 Create new table。加载数据的过程与创建空表的过程相同。
  3. Create Table 页面的 Source Data 部分,执行以下操作:
    • Create from source 保持选中状态。
    • 对于 Location,选择 Cloud Storage,然后在来源字段中输入 Cloud Storage URI。Cloud Storage 存储分区必须与您要创建的表所属的数据集位于同一位置。Datastore 导出文件的 URI 应以 [KIND_NAME].export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是种类名称,default_namespace_kind_Book 是由 Datastore 生成的文件名。

      请验证是否已在 Cloud Storage URI 中指定 [KIND_NAME]。如果指定的 URI 中不含 [KIND_NAME],您会收到以下错误:does not contain valid backup metadata. (error code: invalid)

    • 对于 File format,请选择 Datastore Backup
  4. Create Table 页面的 Destination Table 部分,执行以下操作:
    • 对于 Table name,选择适当的数据集,并在表名称字段中输入要覆盖的表的名称。
    • 验证 Table type 是否设为 Native table
  5. 架构部分中,无需执行任何操作。系统会根据 Datastore 导出文件推断架构。
  6. 对于 Options 部分的 Write preference,选择 Overwrite table
  7. 点击 Create Table

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 文件设置默认位置值。
  • FORMATDATASTORE_BACKUP
  • DATASET:包含要向其中加载数据的表的数据集。
  • TABLE:要覆盖的表。
  • PATH_TO_SOURCECloud 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. configuration.load.sourceFormat 属性设置为 DATASTORE_BACKUP,以指定数据格式。

  5. configuration.load.writeDisposition 属性设置为 WRITE_TRUNCATE,以指定写入处置方式。

Datastore 选项

如需更改 BigQuery 解析 Datastore 导出数据的方式,请在经典版网页界面、命令行界面或 API 中指定其他选项。

CSV 选项 经典版界面选项 “bq”标志 BigQuery API 属性 说明
投影字段 --projection_fields projectionFields 逗号分隔列表,用于指示要从 Datastore 导出文件加载到 BigQuery 中的实体属性。属性名称区分大小写,且必须是顶级属性。如果没有指定属性,BigQuery 将加载所有属性。如果系统在 Datastore 导出文件中找不到任何指定属性,则会在作业结果中返回一个无效错误。默认值为 ''。
允许的错误记录数 允许的错误数 --max_bad_records maxBadRecords (可选)BigQuery 在运行作业时可忽略的错误记录数上限。如果错误记录数超过该值,作业结果中将返回无效错误。默认值为 0,表示所有记录都必须有效。

数据类型转换

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

Datastore 数据类型 BigQuery 数据类型
Blob BYTES
Blobstore STRING
布尔值 BOOLEAN
类别 STRING
数据存储区键 RECORD
日期和时间 TIMESTAMP
电子邮件 STRING
嵌入式实体 RECORD
浮点数 FLOAT
地理点

RECORD


[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
        
IM 句柄 STRING
整数 INTEGER
链接 STRING
电话号码 STRING
邮寄地址 STRING
评分 INTEGER
短 blob BYTES
字符串 STRING(截断至 64 KB)
用户

RECORD


[{"email","STRING"}
 {"userid","STRING"}]
        

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