从 Cloud Datastore 导出文件中加载数据

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

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

通过在 API 中设置 projectionFields 属性或在 CLI 中使用 --projection_fields 标志,您可以控制 BigQuery 应加载哪些属性。

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

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

限制

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

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

所需权限

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

BigQuery 权限

将数据加载到 BigQuery 至少需要以下权限。如果要将数据加载到新的表或分区中,或者要覆盖或附加到表或分区,则必须具有这些权限。

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

以下预定义的 Cloud 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 中的 Cloud IAM 角色和权限,请参阅访问权限控制

Cloud Storage 权限

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

可以通过授予预定义的 Cloud IAM 角色 storage.objectViewer 来提供 storage.objects.getstorage.objects.list 权限。

加载 Cloud Datastore 导出服务数据

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

控制台

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

    转到 BigQuery 网页界面

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

    创建表

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

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

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

      选择数据集

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

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

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

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

经典版界面

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

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

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

CLI

使用 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 Cloud 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 加载 Cloud Datastore 导出数据。

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

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

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

  4. configuration.load.sourceFormat 属性设置为 DATASTORE_BACKUP,以指定数据格式。

Cloud Datastore 管理备份

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

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

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

如果您试图将 Cloud 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

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

控制台

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

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

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

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

    • 对于文件格式,选择 Cloud Datastore 备份

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

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

      选择数据集

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

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

  5. Schema 部分中,无需执行任何操作。系统会根据 Cloud 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 存储分区必须与您要创建的表所属的数据集位于同一位置。Cloud Datastore 导出文件的 URI 应以 [KIND_NAME].export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是种类名称,default_namespace_kind_Book 是由 Cloud Datastore 生成的文件名。

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

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

CLI

使用带有 --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 Cloud 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 结尾。Cloud Datastore 导出文件只能使用一个 URI,且不得使用通配符。

  4. configuration.load.sourceFormat 属性设置为 DATASTORE_BACKUP,以指定数据格式。

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

Cloud Datastore 选项

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

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

数据类型转换

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

Cloud Datastore 数据类型 BigQuery 数据类型
Blob BigQuery 会在加载数据时舍弃这些值。
Blobstore STRING
布尔值 BOOLEAN
类别 STRING
数据存储区键 RECORD
日期和时间 TIMESTAMP
电子邮件 STRING
嵌入式实体 RECORD
浮点数 FLOAT
地理点

RECORD


[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
        
IM 句柄 STRING
整数 INTEGER
链接 STRING
电话号码 STRING
邮寄地址 STRING
评分 INTEGER
短 blob BigQuery 会在加载数据时舍弃这些值。
字符串 STRING(截断至 64 KB)
用户

RECORD


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

数据存储区键属性

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

键属性 说明 BigQuery 数据类型
__key__.app Cloud Datastore 应用名称。 STRING
__key__.id 实体的 ID,或 null(如果设置了 __key__.name)。 INTEGER
__key__.kind 实体的种类。 STRING
__key__.name 实体的名称,或 null(如果设置了 __key__.id)。 STRING
__key__.namespace 如果 Cloud Datastore 应用使用自定义命名空间,该属性即为实体的命名空间。否则,会以空字符串表示默认命名空间。 STRING
__key__.path 经过拼合的祖先实体路径,其中包含从根实体到实体本身的“种类-标识符”对序列。例如:"Country", "USA", "PostalCode", 10011, "Route", 1234 STRING
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

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