从 Firestore 导出文件中加载数据

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

注意：并非所有 Firestore 导出文件都可以加载。请参阅 BigQuery 限制以创建可加载到 BigQuery 表中的 Firestore 导出文件。

限制

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

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

准备工作

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

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

加载 Firestore 导出服务数据

您可以使用 Google Cloud 控制台、bq 命令行工具或 API 从 Firestore 导出元数据文件中加载数据。

有时，Google Cloud 控制台和 bq 命令行工具中会使用 Datastore 术语，但以下流程与 Firestore 导出文件兼容。Firestore 和 Datastore 具有相同的导出格式。

注意：您可以通过在 bq 命令行工具中使用 --projection_fields 标志或通过在 load 作业配置中设置 projectionFields 属性来加载特定字段。

控制台

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

   转到 BigQuery

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

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 标志是可选的。
• FORMAT：DATASTORE_BACKUP。“Datastore 备份”是 Firestore 的正确选项。Firestore 和 Datastore 具有相同的导出格式。
• DATASET：您要向其中加载数据的表所属的数据集。
• TABLE：要向其中加载数据的表。如果该表不存在，系统会创建表。
• PATH_TO_SOURCE：Cloud Storage URI。

例如，以下命令将 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Firestore 导出文件加载到名为 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 加载 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，以指定写入处置方式。

Python

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

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

Firestore 选项

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

Google Cloud 控制台选项	“bq”标志	BigQuery API 属性	说明
不可用	--projection_fields	projectionFields（Java、Python）	（可选）英文逗号分隔列表，用于指示要从 Firestore 导出文件中加载的文档字段。默认情况下，BigQuery 会加载所有字段。字段名称区分大小写，并且必须出现在导出文件中。您不能在映射字段（如 map.foo）中指定字段路径。

数据类型转换

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