从 Firestore 导出文件中加载数据

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

限制

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

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

所需权限

在将数据加载到 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

以下预定义的 Cloud 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 权限。

加载 Firestore 导出服务数据

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

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

控制台

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

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

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

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

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

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

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

      选择数据集。

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

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

  5. 架构部分中,无需执行任何操作。系统会推断 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 存储分区必须与数据集位于同一位置。Firestore 导出文件的 URI 应以 KIND_COLLECTION_ID.export_metadata 结尾。例如:default_namespace_kind_Book.export_metadata。在此示例中,Book 是集合 ID,default_namespace_kind_Book 是 Firestore 生成的文件名。

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

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

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

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

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

  7. 点击 Create Table

bq

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

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

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

替换以下内容:

  • LOCATION:您所在的位置。--location 标志是可选的。
  • FORMATDATASTORE_BACKUP。“Datastore 备份”是 Firestore 的正确选项。Firestore 和 Datastore 具有相同的导出格式。
  • DATASET:您要向其中加载数据的表所属的数据集。
  • TABLE:要向其中加载数据的表。如果该表不存在,系统会创建表。
  • PATH_TO_SOURCECloud Storage URI

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

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

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

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

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

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

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

Firestore 选项

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

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

数据类型转换

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

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

RECORD


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

Firestore 键属性

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

键属性 说明 BigQuery 数据类型
__key__.app Firestore 应用名称。 STRING
__key__.id 文档 ID,或 null(如果设置了 __key__.name)。 INTEGER
__key__.kind 文档的集合 ID。 STRING
__key__.name 文档名称,或 null(如果设置了 __key__.id)。 STRING
__key__.namespace Firestore 不支持自定义命名空间。默认命名空间以空字符串表示。 STRING
__key__.path 文档的路径:以根集合为起点的“集合-文档”对序列。例如:"Country", "USA", "PostalCode", 10011, "Route", 1234 STRING