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

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

所需权限

在将数据加载到 BigQuery 时,您需要拥有项目级或数据集级的权限,才能将数据加载到新的或现有的 BigQuery 表和分区中。如果要从 Cloud Storage 加载数据,您还需要访问包含该数据的存储分区。

BigQuery 权限

如果您要将数据从 Cloud Storage 加载到 BigQuery 中,必须被授予项目级或数据集级的 bigquery.dataOwnerbigquery.dataEditor 角色。这两个角色允许用户和组将数据加载到新表中,或将数据附加到现有表或覆盖现有表。

若授予项目级角色,则用户或组有权将数据加载到项目中任一数据集的表中。若授予数据集级角色,则用户或组只能将数据加载到该数据集的表中。

如需详细了解如何配置数据集访问权限,请参阅控制对数据集的访问权限。要详细了解 BigQuery 中的 IAM 角色,请参阅访问权限控制

Cloud Storage 权限

要从 Cloud Storage 存储分区加载数据,您必须被授予项目级或相应单个存储分区的 storage.objects.get 权限。如果要使用 URI 通配符,您还必须拥有 storage.objects.list 权限。

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

限制

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

  • 您的数据集必须与包含导出文件的 Cloud Storage 存储分区位于同一个区域或多区域位置。
  • 您只能指定一个 Cloud Storage URI,并且不能使用 URI 通配符。
  • Cloud Firestore 导出数据中的文档必须共用一个其独特字段名称数量小于 10000 的一致架构,才能顺利加载。
  • 您可以创建新表来存储数据,也可以覆盖现有表。但您无法将 Cloud Firestore 导出数据附加到现有表中。
  • 导出命令必须指定 collection-ids 过滤条件。未指定集合 ID 过滤条件而导出的数据无法加载到 BigQuery 中。

加载 Cloud Firestore 导出服务数据

您可以使用 BigQuery 网页界面、bq 命令行工具API 从 Cloud Firestore 导出元数据文件中加载数据。

有时,界面或命令中会使用 Cloud Datastore 术语,但请放心,以下流程与 Cloud Firestore 导出文件兼容。Cloud Firestore 和 Cloud Datastore 具有相同的导出格式。

Console

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

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

    • 在来源字段中输入 Cloud Storage URI。Cloud Storage 存储分区必须与您的数据集位于同一位置。Cloud Firestore 导出文件的 URI 应以 [KIND_COLLECTION_ID].export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是集合 ID,default_namespace_kind_Book 是 Cloud Firestore 生成的文件名。

      请核实您的 Cloud Storage URI 中是否指定了 [KIND_COLLECTION_ID]。如果您指定的 URI 不包含 [KIND_COLLECTION_ID],则会收到以下错误:does not contain valid backup metadata. (error code: invalid)

    • 对于 File format,选择 Cloud Datastore Backup。“Cloud Datastore 备份”是 Cloud Firestore 的正确选项。Cloud Firestore 和 Cloud Datastore 具有相同的导出格式。

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

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

      选择数据集

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

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

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

  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 Firestore 导出文件的 URI 应以 [KIND_COLLECTION_ID].export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是集合 ID,default_namespace_kind_Book 是 Cloud Firestore 生成的文件名。

      请核实您的 Cloud Storage URI 中是否指定了 [KIND_COLLECTION_ID]。如果您指定的 URI 不包含 [KIND_COLLECTION_ID],则会收到以下错误:does not contain valid backup metadata. (error code: invalid)

    • 对于 File format,选择 Cloud Datastore Backup。“Cloud Datastore 备份”是 Cloud Firestore 的正确选项。Cloud Firestore 和 Cloud Datastore 具有相同的导出格式。

  4. Create Table 页面的 Destination Table 部分,执行以下操作:

    • Table name 部分,选择适当的数据集,然后在表名称字段中输入要在 BigQuery 中创建的表的名称。
    • 验证 Table type 是否设为 Native table
  5. Schema 部分中,无需执行任何操作。系统会推断 Cloud Firestore 导出文件的架构。

  6. Options 部分中,选择适用项。如果要覆盖现有表,请将写入偏好设置 (Write preference) 设置为覆盖表 (Overwrite table)。

  7. 点击创建表 (Create Table)。

命令行

使用 bq load 命令并将 source_format 设置为 DATASTORE_BACKUP。提供 --location 标志并将值设置为您的位置。如果要覆盖现有表,请添加 --replace 标志。

要仅加载特定字段,请使用 --projection_fields 标志

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

其中:

  • [LOCATION] 是您的位置。--location 是可选标志。
  • [FORMAT]DATASTORE_BACKUP。对于 Cloud Firestore,应选择“Cloud Datastore 备份”。Cloud Firestore 和 Cloud Datastore 具有相同的导出格式。
  • [DATASET] 是一个数据集,它包含您要将数据加载到其中的表。
  • [TABLE] 是您要将数据加载到其中的表。如果该表不存在,系统会创建表。
  • [PATH_TO_SOURCE]Cloud Storage URI

例如,以下命令将 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Cloud Firestore 导出文件加载到名为 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 Firestore 导出数据。

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

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

  3. 在加载作业配置中,sourceUris 必须采用完全限定格式:gs://[BUCKET]/[OBJECT]。文件(对象)名必须以 [KIND_NAME].export_metadata 结尾。只能指定一个 Cloud Firestore 导出文件 URI,且不能使用通配符。

  4. 在加载作业配置中将 sourceFormat 属性设置为 DATASTORE_BACKUP,以指定数据格式。“Cloud Datastore 备份”是 Cloud Firestore 的正确选项。Cloud Firestore 和 Cloud Datastore 具有相同的导出格式。

  5. 要仅加载特定字段,请设置 projectionFields 属性。

  6. 如果要覆盖现有表,请将 writeDisposition 属性设置为 WRITE_TRUNCATE,以指定写入处置方式。

Cloud Firestore 选项

要更改 BigQuery 解析 Cloud Firestore 导出数据的方式,请指定以下选项:

CSV 选项 经典版界面选项 CLI 标志 BigQuery API 属性 说明
投影字段 --projection_fields projectionFields (可选)英文逗号分隔列表,用于指示要从 Cloud Firestore 导出文件中加载的文档字段。默认情况下,BigQuery 会加载所有字段。字段名称区分大小写,并且必须出现在导出文件中。您不能在映射字段(如 map.foo)中指定字段路径。
允许的错误记录数 允许的错误数 --max_bad_records maxBadRecords (可选)BigQuery 在运行作业时可忽略的错误记录数上限。如果错误记录数超过该值,作业结果中将返回无效错误。默认值为 0,表示所有记录都必须有效。

数据类型转换

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

Cloud Firestore 数据类型 BigQuery 数据类型
数组 RECORD
布尔值 BOOLEAN
引用 RECORD
日期和时间 TIMESTAMP
地图 RECORD
浮点数 FLOAT
地理点

RECORD


[{"lat","FLOAT"},
 {"long","FLOAT"}]
        
整数 INTEGER
字符串 STRING(截断至 64 KB)

Firestore 键属性

Cloud Firestore 中的每个文档都有一个唯一键,其中包含文档 ID 和文档路径等信息。BigQuery 会为该键创建一个 RECORD 数据类型(也称为 STRUCT),其中每条信息都有对应的嵌套字段,如下表所示。

键属性 说明 BigQuery 数据类型
__key__.app Cloud Firestore 应用名称。 STRING
__key__.id 文档的 ID;如果设置了 __key__.name,则为 null INTEGER
__key__.kind 文档的集合 ID。 STRING
__key__.name 文档的名称;如果设置了 __key__.id,则为 null STRING
__key__.namespace Cloud Firestore 不支持自定义命名空间。默认命名空间以空字符串表示。 STRING
__key__.path 文档的路径:以根集合为起点的“集合-文档”对序列。例如:"Country", "USA", "PostalCode", 10011, "Route", 1234 STRING
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

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