# @firebase-function-kits/firestore-bigquery-export 中文文档 规范地址：https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/ 版本：0\.1\.1 npm 元数据更新时间：2026-09-28T18:37:43.500Z 中文译文更新时间：2026-11-14T19:25:46.513Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40firebase-function-kits/firestore-bigquery-export 原文对照：https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/?lang=original 项目主页：https://github.com/firebase/extensions#readme 源码仓库：https://github.com/firebase/extensions ## 关键信息（来自 npm 元数据） - 包体积（解压后）：521 kB，76 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：6 个 - 首次发布：2026-08-19T19:14:18.462Z - 最新版本发布：2026-09-28T18:33:48.189Z - 近 30 天下载量：9074（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：21（近 12 个月 21 个） ## 中文简介 将 Cloud Firestore 收藏流到大查询中, 作为可部署的防火基地函数 ## 安装 ```sh npm install @firebase-function-kits/firestore-bigquery-export ``` 也可以使用：`pnpm add @firebase-function-kits/firestore-bigquery-export`、`yarn add @firebase-function-kits/firestore-bigquery-export`、`bun add @firebase-function-kits/firestore-bigquery-export` ## README # @firebase-函数-kits/firestore-bigquery-export 流出一所云火炉收藏到 BigQuery. 这是流火炉 作为 npm 软件包的大查询防火基地扩展, 您会添加到自己的防火基地 函数编码库和部署. 每个文档被序列化并插入到 BigQuery 更改日志表. 失败通过 Cloud 任务队列写入缓冲( E)`syncBigQuery`并且现在 再审. 以下用语:a **代码库** 是云函数源代码 火基地CLI作为单位部署. A 类 **工具包** 由 a 声明的此软件包 `kit` 输入 `firebase.json`。一个 **实例** 是套装的复制件, 拥有自己的 `.env` 和四项功能; 国家领导才能将每个实例作为 以实例 id 命名的代码库 . ## 安装 假设最新的防火基地CLI已经安装并签名,并且您 从您的 Firebase 项目目录( 包含 `firebase.json`· ; `firebase init` 创建),与您的工程相链接 (单位:千美元)`firebase use `) (中文(简体) ). 您还需要云火店 “火焰计划”和“节点24”(22个或以后得到支持). **向导安装器 .** 这创建了下面的代码库 `function-kits//`, (中文(简体) ), 添加 `kit` 条目为 `firebase.json`,每个设置的提示,写 答案为: `function-kits//config-/.env.`数字 : ```sh firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export@latest ``` 它还要求 `FUNCTION_DEFAULT_REGION`。输入区域功能 将运行于( a)`us-central1` 页:1 `nam5`; 见 [地区](https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/#readme-region)) (中文(简体) ). **你自己的密码库.** 从 `functions/` 目录 `firebase init functions` 创建、 安装工具包 + `firebase-functions` 财务报告和审定财务报表 `firebase-admin` 作为直接的依赖,对工具包使用的主要版本 (目前为7和14个)。 该套装的收缩包装 嵌入了自己的拷贝,这是CLI 看不到: 没有他们,部署就失败了 `Couldn't find firebase-functions package in your source code`。 。 。 . ```sh npm install @firebase-function-kits/firestore-bigquery-export@0.1.0 firebase-functions@7 firebase-admin@14 npm install --save-dev typescript@5 ``` ## 需要的仪表 手无所取. 第一次部署时 国家情报组要求你确认这些 角色(`This codebase uses declarative security … Continue? (y/N)`,则 创建工具包服务账户,提供这些工具,并启用API。 别 设置自定义运行时间服务账户. 没有终端(例如CI),没有人可以回答,所以确认 与 `--force`。它接受每分一秒,因此仅限于一个实例: ```sh firebase deploy --only functions: --force ``` | 角色 / API | 为什么 | | --- | --- | | `roles/bigquery.dataEditor` | 创建数据集、表格和视图;插入行 | | `roles/bigquery.user` | 运行大查询任务和实际视图 | | `roles/datastore.user` | 将失败的行写入 `BACKUP_COLLECTION` (总是给予) | | `roles/eventarc.eventReceiver` | 收到 Firestore 触发事件 | | `roles/run.invoker` | 让 Eventarc 和 Cloud 任务引用函数 | | `roles/cloudtasks.enqueuer` | 将失败写入到 `syncBigQuery` | | `firestore.googleapis.com` | 接收文档更改事件 | | `bigquery.googleapis.com` | 写入大查询 | 设置 `EVENTARC_CHANNEL` 还添加 `roles/eventarc.publisher` 财务报告和审定财务报表 `eventarcpublishing.googleapis.com`。对于另一个项目的数据集,赠款 该工具包的服务账户 `bigquery.*` 这里的角色。 对于一个CMEK数据集, 允许大查询服务账户访问您的 KMS 密钥 . ## 使用量 有了你自己的代码库,这种布局保持了代码库和实例 `.env` 输入 `functions/` 目录 `firebase init functions` 创建 : ```text my-project/ .firebaserc firebase.json functions/ package.json # "main": "lib/index.js", "engines": { "node": "24" }, "scripts": { "build": "tsc" } tsconfig.json # compiles src/ to lib/ .env src/index.ts ``` ```ts // functions/src/index.ts export { fsexportbigquery, // Firestore trigger syncBigQuery, // retries failed writes from the queue initBigQuerySync, // creates BigQuery resources after the first deploy setupBigQuerySync, // updates them after later deploys } from "@firebase-function-kits/firestore-bigquery-export"; ``` ```sh # functions/.env — set these before the first deploy COLLECTION_PATH=users DATASET_ID=firestore_export TABLE_ID=users DATABASE_REGION=nam5 # your Firestore database's location DATASET_LOCATION=us # keep BigQuery data near the database BACKUP_COLLECTION=users_bigquery_failures ``` 在部署时,需要你放弃的任何安排(见 [配置](https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/#readme-configuration)) (中文(简体) ). 无 `BACKUP_COLLECTION`,失败的行 每次重试都失败了. ## 部署 在那个 `functions` 条目 `firebase init` 创建, 添加 `kit` 财务报告和审定财务报表 `instances` 财务报告和审定财务报表 删除 `codebase` 联合国 `kit` 条目不能有一个: ```json { "functions": [ { "source": "functions", "kit": "firestore-bigquery-export", "instances": { "default": "functions" }, "predeploy": ["npm --prefix \"$RESOURCE_DIR\" run build"] } ] } ``` `kit` 是您选择的任何名称( 最多40个小写字母, 数字, `_`, (中文(简体) ), `-`) (中文(简体) ). `instances` 将每个实例 id 映射到持有它的目录 `.env`函数 名称得到一个 `kit--` 前缀,所以这个部署 `kit-default-fsexportbigquery` 诸如来. 使用密码库的指令 证明. ```sh firebase deploy --only functions # all instances firebase deploy --only functions: # one instance ``` 与 **最新消息** 火基地CLI. 旧版本可能无法部署 装有问题或部署有问题. **检查它的工作原理.** 第一个部署运行 `initBigQuerySync`创建 数据集,其中包含 `_raw_changelog` 表格(每起变化一行)和a `_raw_latest` 视图(每个文档的当前状态)。 这需要一个 分钟或两分钟; 等 `firebase functions:log --only kit--initBigQuerySync` 显示视图。 然后,在 [基地控制台](https://console.firebase.google.com/),将文档添加到  `COLLECTION_PATH` 藏书。 与 `.env` 从 [使用量](https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/#readme-usage),添加 这个给 `users`数字 : ```text Document ID: alice Fields: name (string) = Alice age (number) = 30 ``` 然后运行这个在 [大查询控制台](https://console.cloud.google.com/bigquery)数字 : ```sql SELECT document_id, operation, data, timestamp FROM `.._raw_changelog` ORDER BY timestamp DESC LIMIT 10 ``` 举例来说,表格是 `.firestore_export.users_raw_changelog`,最新的一行有 `document_id` `alice`, (中文(简体) ), `operation` `CREATE` 财务报告和审定财务报表 `data` `{"name":"Alice","age":30}`。 。 。 . 该行可以花一分钟出现。 如果不见了,就等着 `firebase functions:log --only kit--fsexportbigquery` 显示 `Firestore event received by onDocumentWritten trigger` (单位:千美元) `LOG_LEVEL=info`),然后再次查询. ## 配置 在实例中设置 `.env` (或 `.env.`) (中文(简体) ). 如果设置 不在那里,部署要求你 提出默认,并保存你的 回复 `.env.`。 。 。 . 一个设置 **没有** 在“可以是空白的”下 无法在一条线上部署 `DATASET_ID=`。给出一个值,或者删除行并回答提示. | 新闻 var | 默认 | 可以是空的吗 | 说明 | | --- | --- | --- | --- | | `DATABASE_REGION` | (无) | 对 | Firestore 位置; 设置函数 。 没有默认: 总是设置 | | `COLLECTION_PATH` | `posts` | 没有 | 要导出的收藏; `{wildcard}` 片段匹配子集 | | `DATASET_ID` | `firestore_export` | 没有 | 大查询数据集 | | `TABLE_ID` | `posts` | 没有 | 更改日志表格和视图的前缀 | | `DATASET_LOCATION` | `us` | 没有 | 数据集位置; 仅在数据集创建时使用 | | `DATABASE` | `(default)` | 没有 | Firestore 数据库编号 | | `BIGQUERY_PROJECT_ID` | 项目编号 | 没有 | 数据集项目( 如果有差异) | | `BACKUP_COLLECTION` | (空虚) | 对 | 插入失败的行的 Firestore 收藏 。 建议. | | `MAX_DISPATCHES_PER_SECOND` | `100` | 对 | `syncBigQuery` 调度率(1-500) | | `MAX_ENQUEUE_ATTEMPTS` | `3` | 对 | 在放弃(1-10)之前先排队尝试 | | `TRANSFORM_FUNCTION` | (空虚) | 对 | 插入前转换行的 HTTP 函数的 URL | | `TABLE_PARTITIONING` | `NONE` | 对 | `HOUR`, (中文(简体) ), `DAY`, (中文(简体) ), `MONTH`, (中文(简体) ), `YEAR` 或者说 `NONE` | | `TIME_PARTITIONING_FIELD` | (空虚) | 对 | 分区列名称 | | `TIME_PARTITIONING_FIELD_TYPE` | `omit` | 对 | `TIMESTAMP`, (中文(简体) ), `DATETIME`, (中文(简体) ), `DATE` 或者说 `omit` | | `TIME_PARTITIONING_FIRESTORE_FIELD` | (空虚) | 对 | 将防火栏设置为分区 | | `CLUSTERING` | (空虚) | 对 | 最多可分出4个逗号的列,例如:. `data,document_id,timestamp` | | `WILDCARD_IDS` | `false` | 对 | 添加一个 `path_params` 页:1 `{wildcard}` 作为 JSON 值 | | `USE_NEW_SNAPSHOT_QUERY_SYNTAX` | `no` | 没有 | `yes` 编号 : `no` | | `EXCLUDE_OLD_DATA` | `no` | 对 | 在更新时跳过上一个文档状态( N)`yes` 编号 : `no`(中文(简体) ) | | `VIEW_TYPE` | `view` | 没有 | `view`, (中文(简体) ), `materialized_incremental`, (中文(简体) ), `materialized_non_incremental` | | `MAX_STALENESS` | (空虚) | 对 | 实际观点:例如:. `INTERVAL "8:0:0" HOUR TO SECOND` | | `REFRESH_INTERVAL_MINUTES` | (空虚) | 对 | 已实现视图:刷新间隔(分分钟) | | `KMS_KEY_NAME` | (空虚) | 对 | `projects/

/locations//keyRings//cryptoKeys/` | | `LOG_LEVEL` | `info` | 没有 | `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`, (中文(简体) ), `silent` | | `EVENTARC_CHANNEL` | (未设定) | 对 | 工具箱的频道 [事件](https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/#readme-events); 未设置或空白禁用 | | `EXT_SELECTED_EVENTS` | (未设定) | 对 | 要出版的事件类型; 全部未设定的出版, 无空白的出版 | ## 多个实例 每个实例增加一个条目,每个条目都有自己的配置目录和 `.env`。 。 。 . 整个项目必须具有独特性. ```json "instances": { "users": "instances/users", "orders": "instances/orders" } ``` ## 活动 与 `EVENTARC_CHANNEL` 设置, 函数发布 `onStart` 财务报告和审定财务报表 `onError` 从 触发和 `onSuccess` 从 `syncBigQuery`。每次活动在 两者 `firebase.extensions.firestore-bigquery-export.v1.*` 和扩展名 遗产 `firebase.extensions.firestore-counter.v1.*`; 写出新的触发器 第一个. `EXT_SELECTED_EVENTS` 按确切类型过滤,包括遗留副本. 从扩展导出的一个配置带有其 `EXT_SELECTED_EVENTS` 结束了,所以 请检查date=中的日期值 (帮助). ## 规定 `initBigQuerySync` 第一次部署后运行 `setupBigQuerySync` 之后 后面的,创建或更新数据集、表格和视图(15次尝试,60次) (原始内容存档于2017-09-21). Reference. 没有更改的调用被跳过,同样 `setupBigQuerySync`。写作从不创建资源:如果缺少,写作 失败到队列和备份收藏,直到生命周期任务运行. 要逐一运行,请从您的代码库目录中运行此选项 `firebase-admin` 安装和应用程序默认证书`gcloud auth application-default login`) (中文(简体) ). 惠璶 `roles/cloudtasks.enqueuer`附加时 `roles/iam.serviceAccountUser` 该工具箱的服务账户上 任务; `KIT_SA` 看这个账户: ```sh export GOOGLE_CLOUD_PROJECT= FUNCTION_REGION=us-central1 export KIT_SA=$(gcloud functions describe kit--setupBigQuerySync \ --region "$FUNCTION_REGION" --format 'value(serviceConfig.serviceAccountEmail)') node -e ' const { initializeApp } = require("firebase-admin/app"); const { getFunctions } = require("firebase-admin/functions"); initializeApp({ serviceAccountId: process.env.KIT_SA }); getFunctions() .taskQueue("locations/'"$FUNCTION_REGION"'/functions/kit--setupBigQuerySync") .enqueue({}) .then(() => console.log("enqueued")); ' ``` ## 处理失败 1. 触发器插入行内线. 如果失败, 行将被写入 `BACKUP_COLLECTION` (设定时) 更改顺序在 `syncBigQuery`。 。 。 . 2. `syncBigQuery` 尝试最多5次,至少60多次,然后写信给 `BACKUP_COLLECTION` 每次尝试失败后。 上次之后的任务就是 掉下来了 如果每个案子都忙 Cloud Run都用429来拒绝 在工具包的代码运行前,所以没有写入备份行. 3. 如果队列也失败, 触发器会记录出错, 发布 `onError` 放弃吧 活动没有重新交付. 备份文档以事件 ID 键入, 更改日志列下方 `json`。装入这些 `json` 对象与更改日志的图案放在临时表格中 (例如,导出收藏和 `bq load` 页:1 `json` 页:1 有些人是 被后来成功的失败所留下, 所以把它们与反联合起来 `event_id`数字 : ```sql MERGE `.._raw_changelog` AS target USING `..` AS backup ON target.event_id = backup.event_id WHEN NOT MATCHED THEN INSERT (timestamp, event_id, document_name, document_id, operation, data, old_data) VALUES (backup.timestamp, backup.event_id, backup.document_name, backup.document_id, backup.operation, backup.data, backup.old_data) ``` 与 `WILDCARD_IDS=true`,添加 `path_params` 名单。 有习惯 分区字段,添加您 `TIME_PARTITIONING_FIELD` 栏。 譬如说, 双方和 `TIME_PARTITIONING_FIELD=created_at`数字 : ```sql MERGE `..
_raw_changelog` AS target USING `..` AS backup ON target.event_id = backup.event_id WHEN NOT MATCHED THEN INSERT (timestamp, event_id, document_name, document_id, operation, data, old_data, path_params, created_at) VALUES (backup.timestamp, backup.event_id, backup.document_name, backup.document_id, backup.operation, backup.data, backup.old_data, backup.path_params, backup.created_at) ``` 限制, 全部与扩展共享 : - 插入前的失败( 例如损坏) `TRANSFORM_FUNCTION`没有 备份. - 超过 1 MB 的更改无法被排序 . `EXCLUDE_OLD_DATA=yes` 将更新减半 载荷. - 更改日志可以包含重复 `event_id`s;最新视图为: 不受影响. - 删除或移动函数时,其云任务队列会作为 `DISABLED`。 。 。 . ## 从扩展名移出 从您的 Firebase 项目目录中运行迁移, 命名扩展名 实例以替换(无 `--ext-instance`它让你选一个: ```sh firebase ext:migrate --ext-instance ``` 它输出实例的配置,部署工具包,然后提议 解开分机 在新触发器暖和时写入 也没有出口者。 为了避免空档,对未安装的提示回答否,确认 工具箱记录每封信(见 [看有没有用](https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/#readme-deploy)),然后卸载: ```sh firebase ext:uninstall --immediate ``` 一次运行两者都是安全的: 在共享事件 ID 上进行大查询 (尽最大努力),最新的观点不会受到任何重复的影响. 要恢复已丢失的写入, 请重新导入 [`fs-bq-import-collection`](https://github.com/firebase/extensions/blob/master/firestore-bigquery-export/guides/IMPORT_EXISTING_DOCUMENTS.md), (中文(简体) ), 指向工具包的数据集和表格前缀,而写入则被暂停。 这个 导入每个文档的当前值为 `IMPORT` 行; 删除 替换的更新无法恢复 . ## 从流火炉到大查询扩展的区别 - **地区.** 扩展的安装时云函数位置已消失. 见 [地区](https://npmcn.com/package/%40firebase-function-kits/firestore-bigquery-export/#readme-region)。 。 。 . - **`DATASET_LOCATION` 可更改**,但只有在数据集是 创建。 移动,设置一个新的 `DATASET_ID` 再来回填. - **没有伴行工具.** `fs-bq-import-collection`, (中文(简体) ), `gen-schema-view` 编辑 跨项目的赠款脚本留在扩展存储库中,并就 工具箱的桌子. - **失败 `onStart` 发布** 只日志警告; 扩展失败 执行. - **相同的运行时间设置 .** 货币 1, 扩展大小 CPU, 仅内部 触发入侵、540次任务超时、100起触发事件和500起 `syncBigQuery` (约84 vCPU of regional Cloud Run配额). 提升 `setGlobalOptions({ maxInstances })` 更多的触发量. - **`ext:migrate` 带有全球选项.** 它生成的条目文件应用 扩展的内存、 超时、 侵入和实例限制 `setGlobalOptions`只要一个功能没有设置它自己的。 检查 `EXT_MIGRATED_SYSTEM_*` 数值 `.env`。 。 。 . ### 地区 向该区域部署的职能来自 `DATABASE_REGION`区域 现在的位置, `nam5` 财务报告和审定财务报表 `nam7` 改为 `us-central1`, (中文(简体) ), `eur3` 改为 `europe-west1`。 。 。 . 触发器仍在数据库所在区域起火. 设定 `DATABASE_REGION` 内 `.env` 第一次部署之前; 部署时给出的值仅适用于 从下一个部署. 与 `DATABASE_REGION=` 空白, 函数进入 `FUNCTION_DEFAULT_REGION` 在安装器或迁移生成的代码库中,以其他方式 `us-central1` (或它们目前的区域)。 更改区域删除并重新创建函数 和他们的队列. ## API 表面 - **主要条目** (单位:千美元)`@firebase-function-kits/firestore-bigquery-export`: 四个功能和所有从库条目。 还进口 登记 `afterFirstDeploy` 编号 : `afterRedeploy` 任务. - **图书馆条目** (单位:千美元)`@firebase-function-kits/firestore-bigquery-export/lib`: `handleDocumentWrite` 财务报告和审定财务报表 `handleSyncBigQueryTask` 用于登记触发器 你自己,还有 `ExportConfig`, (中文(简体) ), `ResolvedExportConfig`, (中文(简体) ), `resolveExportConfig`, (中文(简体) ), `toTrackerConfig`, (中文(简体) ), `ViewType`, (中文(简体) ), `DocumentWriteEvent`, (中文(简体) ), `HandlerContext`, (中文(简体) ), `SerializedDocumentChange`, (中文(简体) ), `ChangeType`类型 `ChangeTrackerConfig` 财务报告和审定财务报表 `FirestoreBigQueryEventHistoryTracker`。 。 。 . ## 许可证 阿帕奇 - 2.0 ## 常见问题 ### @firebase-function-kits/firestore-bigquery-export 是什么？ 将 Cloud Firestore 收藏流到大查询中, 作为可部署的防火基地函数 ### 如何安装 @firebase-function-kits/firestore-bigquery-export？ 在项目目录运行 npm install @firebase-function-kits/firestore-bigquery-export，或使用 pnpm add / yarn add / bun add。 ### @firebase-function-kits/firestore-bigquery-export 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @firebase-function-kits/firestore-bigquery-export 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @firebase-function-kits/firestore-bigquery-export 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @firebase-function-kits/firestore-bigquery-export 可以商用吗？ @firebase-function-kits/firestore-bigquery-export 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @firebase-function-kits/firestore-bigquery-export 的下载量有多少？ 根据 npm 官方下载统计，@firebase-function-kits/firestore-bigquery-export 在 2026/10/15 – 2026/11/13 这 30 天内被下载 9,074 次，日均约 302 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @firebase-function-kits/firestore-bigquery-export 还在维护吗？ 最新版本 0\.1\.1 发布于 2026/09/29（1 个月前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/08/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。