Firestore 在 2026 年 1 月发布了代号为 Pipeline Operations 的全新查询引擎，这是自 Firestore 诞生以来最为激进的一次查询能力升级。作为 Firestore Enterprise Edition 的独占功能，Pipeline Operations 引入了超过一百项全新查询能力，彻底重构了 Firestore 的查询模型。本文将从工程实践角度深入剖析这一引擎的设计理念、核心机制与落地策略。
从 Core Operations 到 Pipeline：查询范式的根本转变
在传统的 Firestore Core Operations 中，查询遵循一种隐式的阶段排序逻辑。开发者通过链式调用 where、orderBy、limit 等方法，数据库在内部将这些操作按照固定规则重新排列后执行。这种设计虽然简化了 API 表面，却在复杂查询场景下暴露出明显的表达能力瓶颈。Core Operations 对查询形状有严格限制，开发者必须为几乎所有非平凡查询预先创建索引，且无法在单次查询中完成多阶段聚合计算。
Pipeline Operations 的出现彻底改变了这一局面。它引入了显式的阶段（Stage）概念，开发者可以像搭建数据流水线一样组织查询逻辑。每个阶段都有明确的语义定义，阶段之间的数据流向清晰可预测。更为关键的是，Pipeline Operations 将索引创建从强制要求降级为可选优化，查询可以在没有索引的情况下执行，虽然可能退化为表扫描，但至少能够返回结果而非直接失败。这种设计理念的转变，使得 Firestore 第一次具备了与其他主流 NoSQL 数据库相当的查询灵活性。
从架构层面来看，Pipeline Operations 的查询执行引擎采用了流式处理模型。数据从输入阶段流入，经过各转换阶段的处理，最终以快照形式输出。这种设计天然支持部分结果返回，即使查询超时或内存耗尽，也能返回已处理完成的部分数据，而非全部失败。执行引擎会在必要时对阶段进行重排序以提升性能，但这种优化不会改变查询的语义意图。
阶段体系的系统化拆解
输入阶段：数据源的多种入口
输入阶段是任何 Pipeline 查询的起点，定义了查询的初始数据范围。Pipeline Operations 提供了四种输入阶段，每种适用于不同的业务场景。collection 阶段接收一个集合路径作为参数，返回该集合下的所有文档，这是最常用的输入方式。collectionGroup 阶段则跨所有同名子集合查询，特别适合需要穿透嵌套结构的场景，例如查询所有用户的所有订单。
database 输入阶段是一个值得特别关注的新特性，它允许查询返回数据库中的所有文档，不受集合边界的限制。这个功能在数据审计、全库统计等场景下具有独特价值，但使用时需要格外谨慎，因为它可能返回远超预期的大量数据。documents 输入阶段则模拟了批量读取的行为，接收一组文档引用，直接返回这些指定文档的内容，本质上等同于一次批量读取操作。
需要强调的是，所有输入阶段的返回结果顺序都是不稳定的。如果业务对结果顺序有要求，必须显式添加 sort 阶段来定义排序逻辑。这一设计选择使得输入阶段可以采用最优化的数据获取策略，而将排序负担转移到专门的转换阶段。
筛选阶段：Where 的增强与组合
where 阶段承担着传统查询中过滤器的角色，但其表达能力已远超 Core Operations 的能力边界。在 Core Operations 中，复合查询的条件组合受到严格限制，大规模 in 查询或复杂 or 条件的性能表现不尽如人意。Pipeline Operations 的 where 阶段支持任意复杂的布尔表达式，可以通过 and、or、not 函数自由组合条件子句。
多个 where 阶段可以链式调用，系统会自动将它们合并为单一的 and 表达式。这种写法在逻辑等价的前提下提供了更好的可读性。以下两种写法在语义上完全相同，开发者可以根据个人风格选择：
// 链式写法
const results = await execute(db.pipeline()
.collection("books")
.where(field("rating").equal(5))
.where(field("published").lessThan(1900))
);
// 等价的单一表达式写法
const results = await execute(db.pipeline()
.collection("books")
.where(and(
field("rating").equal(5),
field("published").lessThan(1900)
))
);
where 阶段的表达式求值遵循三值逻辑，任何非 true 的结果都会导致文档被过滤。这意味着 false 和 null（可能由错误表达式产生）都会导致文档排除在结果之外。开发者在编写复杂表达式时需要注意这种行为，避免因对 null 值的错误假设导致意外的数据丢失。
投影阶段：字段的选择与变换
select、add_fields 和 remove_fields 三个阶段共同构成了 Pipeline Operations 的投影体系。select 阶段类似于传统 SQL 中的 SELECT 语句，指定返回文档中应包含哪些字段。add_fields 阶段则允许在现有文档结构基础上添加新字段，这些新字段可以是对现有数据的计算结果。remove_fields 提供了一种便捷的方式来排除不需要的字段。
这三个阶段在处理大型文档时尤为重要。假设一个文档包含数十个字段，但前端页面只需要其中的三到四个，使用投影阶段可以在服务器端完成字段过滤，不仅减少了网络传输量，还降低了数据库层的序列化开销。对于包含大量嵌套结构或大型数组的文档，合理的投影策略可以将响应大小降低一个数量级。
值得注意的是，select 和 add_fields 阶段都支持将表达式的计算结果写入用户指定的字段名。如果表达式求值过程中发生错误，该字段的值将被设置为 null 而非抛出异常。这种容错设计确保了单个字段的计算错误不会导致整个查询失败，但开发者需要意识到这种隐式的 null 填充行为。
聚合阶段：服务端计算的深化
aggregate 和 distinct 阶段代表了 Pipeline Operations 在服务端计算能力上的重大突破。aggregate 阶段允许在数据库内部完成复杂的聚合运算，支持 average、count、sum、min、maximum 等累积函数。通过可选的 grouping 参数，可以将输入文档按指定字段分组，为每组分别计算聚合值。
distinct 阶段是 aggregate 的简化形式，专门用于去重场景。它接受一组字段作为去重键，返回每种唯一组合的一个代表文档。与 aggregate 类似，distinct 也支持在字段上应用转换函数后再进行去重，例如将作者名字统一转为大写后再去重，可以避免因大小写差异导致的重复计数问题。
聚合阶段的设计使得过去需要在客户端或 Cloud Functions 中完成的统计工作可以直接在数据库层执行。以电商场景为例，计算每个商品类别的平均评分、最高最低价等统计信息，可以在单次查询中完成，避免了数据在网络间的往返传输。对于需要频繁执行汇总报表的应用，这种设计可以显著降低整体延迟和带宽消耗。
排序与限制：结果集的塑形
sort 和 limit 阶段提供了对结果集进行塑形的能力。sort 阶段接收一个或多个字段及排序方向的定义，支持升序和降序排列。limit 阶段则限制返回文档的数量。需要特别注意的是，在 Pipeline 中阶段的执行顺序对结果有直接影响。如果将 limit 放在排序之前，得到的是排序前的 N 条记录的子集；而如果将 limit 放在排序之后，得到的是排序后最优的 N 条记录。
这种行为差异在实际应用中具有重要意义。以获取评分最高的三本图书为例，错误的阶段顺序可能返回任意三本书而非评分最高的三本。正确的做法是先通过 sort 阶段按评分降序排列，再使用 limit(3) 截取前三名。Pipeline Operations 的显式阶段设计使得这种逻辑清晰可见，避免了 Core Operations 中隐式重排序可能带来的困惑。
字段引用与常量值的语义区分
Pipeline Operations 的表达式系统要求开发者明确区分字段引用和常量值。这种区分在简单查询中可能显得多余，但在复杂表达式中至关重要。field 函数用于引用文档中的字段值，而 constant 函数则用于表示字面量常量。
考虑一个查询场景：筛选名称等于字符串 "Toronto" 的城市。正确的写法需要使用 constant("Toronto") 来表示常量字符串 "Toronto"，而不是直接传递字符串值。这种显式区分在处理数值类型时尤为重要，因为数值 1000 既可能是字段值也可能是常量，通过 field("population") 和 constant(1000) 的明确区分可以消除歧义。
这种设计还支持更为复杂的表达式编写。开发者可以在单个表达式中混合使用字段引用和常量，构建出丰富的计算逻辑。例如，计算折扣后的价格可以写成 field("price").multiply(constant(0.9))，这种表达式在 select 或 add_fields 阶段中可以生成计算字段，避免了在客户端进行二次处理的需要。
函数体系：两大类型与典型应用
Pipeline Operations 提供了丰富的函数库，大致可分为标量函数和聚合函数两大类。标量函数用于非聚合阶段的表达式求值，对每条输入文档独立计算。聚合函数则用于 aggregate 阶段，在整个数据集上累积计算。
标量函数的典型应用场景包括字符串处理（如 toUpper、substring）、数值运算（如 add、multiply）、类型转换（如 toString、toInt）以及条件判断（如 coalesce、ifNull）。这些函数可以在 where 阶段的过滤条件中使用，也可以在 select 阶段的投影表达式中使用。
聚合函数包括 minimum、maximum、average、sum、count 等。在 aggregate 阶段中使用这些函数时，系统会自动维护累积状态，最终返回计算结果。值得注意的是，聚合函数与同名的标量函数在语义上存在差异。以 minimum 为例，标量版本 logicalMinimum 返回每条记录中两个字段的较小值，而聚合版本 minimum 则返回整个数据集中某字段的最小值。
可选索引机制与性能权衡
Core Operations 的一个核心约束是索引强制要求 —— 几乎所有非平凡查询都需要预先创建索引，否则查询会直接失败并返回 FAILED_PRECONDITION 错误。Pipeline Operations 将这一约束降级为可选：查询可以在没有索引的情况下执行，但性能可能显著下降。
这种设计背后的理念是开发效率优先于默认性能。在原型开发或数据探索阶段，开发者无需担心索引配置问题，查询总能得到执行结果。当应用进入生产阶段后，可以通过 query explain 工具分析查询是否充分利用索引，并针对性地创建所需索引。
索引创建的策略与 Core Operations 类似但不完全相同。Pipeline Operations 推荐的索引字段顺序为：首先列出所有等值过滤字段（顺序无关），然后是排序字段（顺序需与查询一致），最后是范围或不等值过滤字段（按选择性强弱降序排列）。遵循这一原则可以最大化索引的利用率。
索引密度是另一个需要考虑的因素。Firestore 支持稠密索引和稀疏索引两种模式。稠密索引为每个文档创建完整的索引条目，适合查询模式变化频繁的场景。稀疏索引则只为包含特定字段的文档创建索引条目，可以节省存储空间但需要额外处理缺失字段的情况。根据实际查询模式选择合适的索引密度，可以在存储成本和查询性能之间取得平衡。
执行边界与错误处理
Pipeline Operations 定义了两个关键的执行边界：60 秒的截止时间限制和 128 MiB 的内存使用上限。查询必须在 60 秒内完成，否则会收到 DEADLINE_EXCEEDED 错误。查询执行过程中实例化的中间数据不能超过 128 MiB，否则会收到 RESOURCE_EXCEEDED 错误。
这两个边界是 Firestore 多租户环境下的资源保护机制，确保单个查询不会过度占用共享资源。当遇到这些错误时，开发者需要从查询优化或架构设计的角度寻找解决方案。常见的优化策略包括：添加更精确的过滤条件减少处理数据量、创建适当的索引加速查询执行、将复杂聚合拆分为多个简单查询分步执行等。
INTERNAL 错误表示查询执行过程中遇到了未预期的服务器端问题，通常需要联系支持团队进行排查。这类错误相对罕见，但一旦出现往往意味着底层基础设施层面存在问题。
当前限制与演进预期
作为 Preview 阶段的功能，Pipeline Operations 尚存在若干已知限制。部分索引类型尚未支持，包括 array-contains 索引和 vector 索引。对于涉及数组成员判断或向量相似度搜索的查询，系统会尝试使用其他可用的索引，导致性能不如预期。这一限制预计在后续版本中逐步解除。
分页支持是另一个正在完善的功能领域。Core Operations 提供的 startAfter 和 endBefore 游标机制在 Pipeline Operations 中尚未直接支持。开发者可以通过组合 where 和 sort 阶段来模拟分页行为，利用上一次查询的最后一个文档作为下一次查询的起始标记。
模拟器支持和离线 / 实时能力同样处于开发阶段。目前在本地开发环境中无法使用 Pipeline Operations，需要连接到云端 Firestore 实例。实时监听和离线缓存功能也尚未集成到 Pipeline 查询中，这意味着 Pipeline Operations 主要适用于一次性查询场景，而非需要持续同步的交互式应用。
工程实践建议
对于考虑采用 Pipeline Operations 的团队，以下实践建议可供参考。首先，在原型阶段充分利用可选索引的便利性，快速验证查询逻辑的正确性。当查询模式稳定后，投入精力优化索引配置，确保生产环境的性能表现。其次，对于包含大量聚合计算的报表类查询，优先考虑在 Pipeline 中完成服务端聚合，而非将原始数据拉到客户端处理。这种策略可以显著降低网络开销和客户端内存压力。
投影阶段的使用值得特别关注。在设计查询时，养成明确指定所需字段的习惯，避免返回完整的文档结构。对于大型文档，这种习惯可以带来可观的带宽节省和延迟改善。同时，注意检查聚合表达式中可能产生的错误值，确保 null 填充行为不会破坏业务逻辑。
最后，建立完善的查询监控机制。利用 Firestore 的查询洞察工具定期分析慢查询，识别可以优化的查询模式。当发现查询频繁触发 DEADLINE_EXCEEDED 或 RESOURCE_EXCEEDED 错误时，需要重新审视查询设计或数据模型，寻找根本性的优化方案。
资料来源：
- Firebase 官方文档：Get data with Firestore Pipeline operations（https://firebase.google.com/docs/firestore/pipelines/get-started-with-pipelines）
- Firebase Blog：Unveiling Firestore Pipeline operations（https://firebase.blog/posts/2026/01/firestore-enterprise-pipeline-operations/）