MongoDB: 聚合管道进阶：复杂表达式与转换
最后更新：2026-08-26
聚合管道进阶——掌握复杂表达式和类型转换能解决 90% 的数据分析场景。
聚合管道进阶的学习路径：本课程从条件表达式（$cond/$switch/$ifNull）开始，依次学习日期操作、类型转换、字符串操作、数组操作，最后综合实战。每个主题独立但相互关联——条件表达式在日期操作的"判断工作日/周末"中使用，类型转换在"$toString 格式化日期"中使用，字符串操作在"拼接显示文本"中使用。理解这种关联有助于构建完整的知识网络。
聚合管道的表达式体系：MongoDB 聚合管道的表达式分为五类——1. 布尔表达式（$cond/$switch/$ifNull/$and/$or/$not）：条件判断和逻辑组合；2. 比较表达式（$eq/$gt/$gte/$lt/$lte/$ne/$cmp）：值的比较；3. 算术表达式（$add/$subtract/$multiply/$divide/$mod/$round）：数值计算；4. 字符串表达式（$concat/$substr/$toUpper/$toLower/$split）：文本处理；5. 数组表达式（$map/$filter/$reduce/$arrayElemAt/$size）：数组变换。掌握这五类表达式，就能组合出任意复杂的数据变换逻辑。
表达式分类的速记方法：五类表达式可以用"判断→比较→计算→文本→数组"的流程记忆——1. 先判断（布尔）：需不需要计算？选哪个分支？2. 再比较：值是否满足条件？3. 再计算：满足条件后做算术运算；4. 再格式化：把计算结果转为展示文本；5. 再处理集合：对数组做批量操作。这个流程正好对应报表计算的典型步骤——判断分组条件 → 比较阈值 → 计算统计值 → 格式化输出 → 处理数组字段。
表达式组合的威力：聚合管道的真正威力来自表达式组合——单个表达式做简单变换，组合起来能解决复杂业务问题。示例：计算"用户等级标签"= $switch(条件: $gte(totalSpent, 10000) → 'VIP') → $concat(标签 + 消费额字符串) → 输出"VIP ¥15,800"。这条链组合了 $switch（条件）、$gte（比较）、$concat（字符串拼接）、$toString（类型转换）四类表达式。理解表达式组合是"会用聚合管道"和"精通聚合管道"的分水岭——前者只会单个操作符，后者能组合构建任意数据管道。
1. 你将学到
- $group 累加器的高级用法
- 条件表达式 $cond / $ifNull / $switch
- 日期提取 $year / $month / $dayOfWeek
- 日期格式化 $dateToString
- 类型转换 $toString / $toInt / $toDecimal
- 数组操作 $arrayElemAt / $map / $filter
graph LR
A[文档] -->|$cond<br/>三元| B[条件投影]
A -->|$switch<br/>多分支| C[分类标签]
A -->|$ifNull<br/>空值处理| D[默认值替换]
A -->|$dateToString<br/>日期格式| E[字符串日期]
A -->|$toInt/$toDecimal<br/>类型转换| F[类型转换]
style B fill:#d4edda
style C fill:#d4edda
2. 条件表达式
概念说明：条件表达式是聚合管道中的"逻辑控制流"，让文档中的每个值根据条件动态计算。$cond 是三元表达式（if-then-else），$switch 是多分支匹配（类似 switch-case），$ifNull 是空值替换（提供默认值）。它们在 $project、$addFields、$group 中广泛使用。
条件表达式的选择决策树：选择哪个条件表达式取决于场景——1. 只需要处理 null → $ifNull（最简单，如 {$ifNull: ['$nickname', '$username']}）；2. 需要 if-else 二选一 → $cond（如 {$cond: [{$gte: ['$age', 18]}, 'adult', 'minor']}）；3. 需要 3+ 分支 → $switch（如按消费金额分层：VIP/Silver/Bronze）；4. 需要"找不到则返回默认值" → $switch + default（类似 SQL 的 CASE WHEN ... ELSE）。决策原则：能用 $ifNull 就不用 $cond，能用 $cond 就不用 $switch——简单性优先，只在需要时引入复杂度。
工作原理：$cond 对每个文档评估 if 条件，返回 then 或 else 值。嵌套 $cond 可实现多级条件，但可读性差——这时用 $switch 更清晰。$ifNull 检查字段是否为 null/undefined，是则替换为备选值。所有条件表达式都是逐文档执行的，不影响其他文档。
graph TB
A[条件表达式] --> B[$cond<br/>三元 if-else]
A --> C[$switch<br/>多分支匹配]
A --> D[$ifNull<br/>空值替换]
B --> E["price >= 1000 → 'expensive'<br/>else price >= 100 → 'medium'<br/>else → 'cheap'"]
C --> F["status = 'paid' → '已支付'<br/>status = 'shipped' → '已发货'<br/>default → '未知'"]
D --> G["nickname 为 null<br/>→ 替换为 username"]
style B fill:#d4edda
style C fill:#cce5ff
style D fill:#fff3cd
| 表达式 | 语法 | 适用场景 | 可读性 |
|---|---|---|---|
$cond |
{if, then, else} |
2 分支条件 | 中等 |
嵌套 $cond |
else 中再嵌套 $cond |
3+ 分支 | 差 |
$switch |
{branches, default} |
3+ 分支 | 好 |
$ifNull |
{ $ifNull: [expr, default] } |
null 值处理 | 好 |
条件表达式的计算模型：条件表达式（$cond/$switch/$ifNull）在聚合管道中逐文档执行——每个文档独立计算自己的条件结果，不同文档之间互不影响。这意味着 $cond 不会短路其他文档的计算，也不存在跨文档的状态共享。理解这一点有助于避免常见错误：在 $cond 中引用其他文档的字段是不可能的，需要先 $lookup 关联再计算。
条件表达式的性能对比：三种条件表达式的性能差异——1. $ifNull：最快（只判断 null/undefined，单次比较）；2. $cond：中等（三元条件，if/then/else 各执行一次表达式）；3. $switch：最慢（顺序评估每个 branch 的 case，直到匹配为止）。性能差距在单文档级别可忽略（微秒级），但在百万级文档的聚合管道中累积效应明显。优化建议：1. 简单 null 替换用 $ifNull 而非 $cond（{ifNull: ['$field', default]} vs {cond: [{eq: ['$field', null]}, default, '$field']}）；2. $switch 的 branches 按命中概率排序（最常命中的 case 放前面，减少平均评估次数）；3. 嵌套 $cond 超过 3 层时必须改用 $switch（可读性和性能都更优）。
$group 累加器的内部原理：$group 的累加器（$sum/$avg/$min/$max/$push/$addToSet）在内存中维护一个状态变量，每处理一个文档就更新一次状态。$sum 初始值为 0，每文档加字段值；$avg 维护 sum + count 两个变量，最后相除；$push 追加到数组；$addToSet 追加不重复值。理解累加器原理有助于设计高效的 $group——避免在 $group 中使用 $push 收集大数组（内存消耗高），改用 $sum 计数或先 $project 精简字段。
聚合 vs MapReduce：MongoDB 早期用 MapReduce 做复杂数据分析，聚合管道是更现代的替代方案。聚合管道的优势：1. 声明式——只需描述"做什么"而非"怎么做"，优化器自动选择执行计划；2. 管道式——阶段串联，每阶段只关注自己的逻辑；3. 性能——聚合管道用 C++ 实现，MapReduce 用 JavaScript 解释执行，性能差 10-100 倍。MongoDB 5.0 已废弃 MapReduce，聚合管道是唯一推荐的分析工具。
聚合管道进阶的学习路径：聚合管道进阶涵盖 5 大类操作——条件表达式（$cond/$switch/$ifNull）、日期操作（$year/$dateToString）、类型转换（$toString/$toInt/$toDecimal）、字符串操作（$concat/$substr/$toUpper）、数组操作（$arrayElemAt/$size/$map/$filter）。这 5 类不是孤立的，在实际管道中交织使用——$group 统计 → $switch 条件分层 → $dateToString 格式化 → 输出。掌握进阶操作是构建复杂报表的基础。
条件表达式的选择决策树：选择哪种条件表达式的决策逻辑——1. 只需判断空值？→ $ifNull（最简洁，专门为此设计）；2. 只有两个分支？→ $cond（对象语法 {if, then, else} 更可读，数组语法 [条件, 真值, 假值] 更紧凑）；3. 三个以上分支？→ $switch（branches 数组逐一匹配，default 兜底，可读性远优于嵌套 $cond）；4. 需要同时判断多个空值？→ $ifNull 链式调用（$ifNull: [$a, $ifNull: [$b, 'default']]）或 $switch + $eq: [null, '$field']。选对表达式大幅提升管道可读性。
条件表达式的性能对比：三种条件表达式的性能从高到低——$ifNull > $cond > $switch。$ifNull 最快因为只检查 null/undefined 一种条件；$cond 稍慢因为需要评估 if 表达式；$switch 最慢因为需要逐一评估 branches 数组中的每个 case。但性能差异通常 < 1ms/千文档，可读性比性能更重要——100 个分支的嵌套 $cond 比 $switch 更难维护，此时 $switch 的可读性收益远超性能代价。
(1) $cond 三元运算符
条件表达式选型指南：三种条件表达式的选择依据——$cond 适合 2 分支条件（如"价格>=1000→expensive/cheap"），语法简洁但嵌套可读性差；嵌套 $cond 理论上能实现多分支，但三层以上就难以维护；$switch 是 3+ 分支的最佳选择（如订单状态映射为中文标签），branches 数组清晰易读，default 处理未匹配情况；$ifNull 专门处理空值替换（如 nickname 为空时用 username），是防御性编程的必备工具。
// === 类似 if-else ===
db.products.aggregate([
{
$project: {
title: 1,
priceLevel: {
$cond: {
if: { $gte: ['$price', 1000] },
then: 'expensive',
else: {
$cond: {
if: { $gte: ['$price', 100] },
then: 'medium',
else: 'cheap'
}
}
}
}
}
}
]);
(2) $ifNull 空值处理
$ifNull 的常见使用场景：$ifNull 在数据分析中有三类典型场景——1. 默认值替换：$ifNull: ['$nickname', '$username'] 显示名不存在时用用户名；2. 计算防护：$ifNull: ['$discount', 0] 折扣为 null 时视为 0（避免 null 参与算术运算导致结果为 null）；3. 标记缺失数据：$ifNull: ['$lastLoginAt', 'never'] 从未登录的用户标记为 'never'。这些场景的共同点是：null 是数据的"黑洞"——任何运算碰到 null 都返回 null，$ifNull 是唯一的"逃生出口"。
null 传播问题：MongoDB 聚合管道中的 null 传播是隐式且危险的——任何表达式只要有一个输入为 null，整个表达式就返回 null。例如：$add: ['$price', '$tax'] 如果 tax 为 null，结果就是 null 而非 price + 0。这不是 bug 而是 SQL 的标准行为（null + anything = null），但在数据分析中常常导致整列数据变成 null。防御策略：1. 在 $project/$addFields 阶段用 $ifNull 处理所有可能为 null 的字段；2. 在数据入库时设 default 值（如 tax: {type: Number, default: 0}）；3. 用 $convert + onNull 统一处理类型转换中的 null。
null 传播的排查方法：聚合管道输出中出现意外 null 时的排查步骤——1. 逐阶段检查：每次只加一个 $addFields，看 null 从哪个阶段开始出现；2. 检查源字段：用 $project 单独输出可疑字段（如 {tax: 1, price: 1}），确认原始值是否为 null；3. 检查计算链：$add → $multiply → $divide 的链式计算中，任何一步为 null 都会传播到后续所有步骤；4. 防御性编码习惯：所有算术表达式都用 $ifNull 包裹——$add: [{$ifNull: ['$price', 0]}, {$ifNull: ['$tax', 0]}]。养成习惯后，null 传播问题几乎不会出现。
// === 替换 null/undefined ===
db.users.aggregate([
{
$project: {
name: 1,
displayName: {
$ifNull: ['$nickname', '$username'] // nickname 为空时用 username
}
}
}
]);
(3) $switch 多条件分支
$switch 的分支顺序与性能：$switch 按分支声明顺序依次评估，第一个匹配的分支即为结果——因此应将最可能匹配的分支放在前面，减少不必要的条件评估。与嵌套 $cond 相比，$switch 的可读性显著更好——3 个以上分支时，嵌套 $cond 的缩进层次过深，$switch 扁平结构一目了然。$switch 的 default 分支不可省略——如果没有任何分支匹配且无 default，MongoDB 会报错。
$switch 在数据清洗中的应用：$switch 在 ETL 数据清洗中有三个典型用法——1. 枚举值映射：将数据库内部编码转换为可读标签（status: 'A' → '活跃'、'I' → ' inactive'、'D' → '已删除'）；2. 分桶标记：将连续值离散化（金额 < 100 → '小额'、100-1000 → '中额'、> 1000 → '大额'，与 $bucket 功能类似但更灵活，可自定义边界和标签）；3. 多条件综合评分：根据多个字段的组合给出评级（VIP 条件：消费 > 10000 且注册 > 1 年；Gold 条件：消费 > 1000 或注册 > 3 年；否则 Bronze）。$switch 的灵活性使其成为数据变换的万能工具。
条件表达式在 ETL 中的应用：条件表达式是 ETL 数据清洗的核心工具——1. 数据分类：$switch 将订单状态转为业务标签（pending→待支付、paid→已支付、shipped→已发货）；2. 异常处理：$ifNull 将缺失字段替换为默认值，$cond 将异常值标记为"需人工审核"；3. 数据脱敏：$cond 将手机号中间四位替换为 （{$concat: [{$substr: ['$phone', 0, 3]}, '', {$substr: ['$phone', 7, 4]}]}）；4. 业务规则：$switch 将用户消费金额映射为等级标签。ETL 管道中，条件表达式通常放在 $addFields 阶段。
条件表达式的选型决策：$cond vs $switch vs $ifNull 的选择——1. 二选一用 $cond：条件只有 true/false 两个分支（如 isVIP: {$cond: [{$gte: ['$spend', 10000]}, true, false]}）；2. 多分支用 $switch：3 个以上条件分支（如等级判定、状态映射）；3. 空值兜底用 $ifNull：只需处理 null/undefined 的情况（如 {$ifNull: ['$nickname', '$username']}）；4. 嵌套条件先 $switch：避免嵌套 $cond（3 层以上嵌套可读性极差），用 $switch 的扁平结构替代。经验法则——2 个分支用 $cond，3+ 分支用 $switch，null 处理用 $ifNull。
// === 类似 switch-case ===
db.orders.aggregate([
{
$project: {
orderId: '$_id',
statusLabel: {
$switch: {
branches: [
{ case: { $eq: ['$status', 'pending'] }, then: '待支付' },
{ case: { $eq: ['$status', 'paid'] }, then: '已支付' },
{ case: { $eq: ['$status', 'shipped'] }, then: '已发货' },
{ case: { $eq: ['$status', 'delivered'] }, then: '已送达' }
],
default: '未知状态'
}
}
}
}
]);
3. 日期操作
概念说明：日期操作是时序数据分析的基础。MongoDB 提供三类日期操作符：(1) 提取类（$year/$month/$dayOfMonth/$hour 等），从 Date 字段提取时间分量；(2) 格式化类（$dateToString），将 Date 转为指定格式的字符串；(3) 运算类（$add/$subtract），对日期进行加减计算。
工作原理：提取操作符直接从 BSON Date 类型读取对应分量，支持 timezone 参数处理时区。$dateToString 使用类似 strftime 的格式符输出字符串。日期运算基于毫秒时间戳：$add 加毫秒数，$subtract 计算时间差，再除以常量转换为天/小时。
时区策略的选择：日期操作的时区处理有两种策略——1. 存储层统一 UTC（推荐）：所有日期以 UTC 存储，查询时用 timezone 参数转换为本地时间显示；2. 存储层带时区：每个文档记录 timezone 字段，查询时引用。策略 1 的优势：查询条件不需要考虑时区转换，日期比较直接准确；跨时区查询不需要复杂的时区换算。策略 2 适用于需要精确记录"用户在哪个时区的什么时间操作"的审计场景。
日期索引优化：按日期范围查询（如"最近 7 天的订单"）是最常见的时序查询。优化要点：1. createdAt 字段默认有索引（timestamps: true + 默认索引）；2. 日期范围查询应用 $gte + $lt 而非 $where 或聚合；3. 复合索引 {status: 1, createdAt: -1} 同时覆盖"按状态筛选+按日期排序"；4. $dateToString 不走索引——它将 Date 转为字符串后比较，应先 $match 日期范围再 $dateToString 格式化。
日期分组统计的常见模式：日期分组是时序分析的核心——按日/周/月/季度/年分组统计。分组键的设计：1. 按月分组：{_id: {year: {$year: '$date'}, month: {$month: '$date'}}}；2. 按周分组：{_id: {year: {$year: '$date'}, week: {$week: '$date'}}}；3. 按日分组：$dateToString: {format: '%Y-%m-%d', date: '$date'} 作为 _id。注意：$dateToString 方式不走索引，但语法最简洁。按月/周分组用提取函数可以利用复合索引先过滤再分组。
缺失日期的填充技巧：按日分组的统计结果可能缺少某些日期（如某天没有订单，结果中就没有该日期的条目），前端绘制连续折线图时会出现断点——1. 应用层填充：Node.js 遍历日期范围，缺失日期填充 0 值（最常用，代码简洁）；2. $densify 阶段（MongoDB 6.1+）：{$densify: {field: 'date', range: {step: 1, unit: 'day', bounds: 'full'}}} 自动填充缺失日期（纯管道方案，无需应用层处理）；3. 辅助集合：创建 calendar 集合预存所有日期，用 $lookup 关联填充（兼容旧版本但维护成本高）。方案 2 最优雅但需要 MongoDB 6.1+，方案 1 最通用。
日期范围查询的最佳实践：查询"最近 N 天"的正确写法——1. 用 $gte + new Date(Date.now() - N86400000)（JavaScript 计算，传 Date 对象给 MongoDB）；2. 用 $gte + ISODate()（mongo shell 语法）；3. 在聚合管道中用 $match + $expr + $gte: ['$createdAt', {$subtract: ['$$NOW', N86400000]}]（纯管道表达式，$$NOW 引用服务器当前时间）。方案 3 最灵活——不依赖应用层计算时间，管道内自包含。
graph LR
A[Date 字段<br/>2026-07-01T10:30:00Z] --> B[$year → 2026]
A --> C[$month → 7]
A --> D[$dayOfMonth → 1]
A --> E[$hour → 10]
A --> F["$dateToString<br/>%Y-%m-%d → '2026-07-01'"]
A --> G["$add[date, 7*86400000]<br/>→ 2026-07-08"]
A --> H["$subtract[now, date]<br/>→ 天数差"]
style B fill:#d4edda
style F fill:#cce5ff
style G fill:#fff3cd
日期运算的精度问题：$subtract 计算日期差返回毫秒数，除以 86400000 转换为天数时存在精度问题——夏令时切换会导致某天不是精确的 24 小时。精确计算应使用 $dateToString 提取日期部分后比较，或用 $dayOfYear 差值近似。大多数业务场景下，毫秒精度足够，但金融和考勤系统需要特别注意。
日期操作的常见错误：1. 时区混淆——存储 UTC 但显示本地时间时忘记转换；2. 月份从 1 开始但 JavaScript Date 从 0 开始（MongoDB $month 返回 1-12，与 JavaScript 不同）；3. $dayOfWeek 返回 1=Sunday（美式习惯，中国用户可能期望 1=Monday）；4. $week 返回年内周数，但不同国家对"一周从哪天开始"定义不同（ISO 8601 规定周一为一周开始，MongoDB 默认周日）；5. $add 加毫秒数不处理闰秒（对绝大多数应用无影响）。
日期操作的性能优化：日期操作在聚合管道中不使用索引——$year/$month 等提取函数先将 Date 转为数值再比较，无法利用 Date 字段的 B-tree 索引。因此：1. 按日期范围查询用 $gte/$lt（直接在 Date 字段上比较，走索引）而非 $month === 7；2. 按月分组时用 {$gte: startOfMonth, $lt: startOfNextMonth} 过滤后再 $group；3. $dateToString 只在最终输出阶段使用（格式化），不在过滤阶段使用。
日期的最佳实践总结：MongoDB 日期操作的黄金法则——1. 存储始终用 UTC（避免时区混乱，显示时在应用层或 $dateToString 的 timezone 参数转换）；2. 查询始终用 $gte/$lt（走索引，不用 $month/$year 等提取函数过滤）；3. 分组用 $dateToString 或 $dateFromParts 构造分组键（如 "$dateToString: {format: '%Y-%m', date: '$createdAt'}"按月分组）；4. 格式化只在输出层（$project/$addFields 的最后一步）；5. 时区在 $dateToString 的 timezone 参数指定（IANA 格式如 'Asia/Shanghai'），不要在应用层手动偏移小时数（夏令时会让偏移量变化）。
(1) 日期提取
时区处理策略：MongoDB 存储 Date 为 UTC 时间戳（无时区信息），日期提取操作符默认返回 UTC 值。对于需要本地时间的场景：1. $dateToString 的 timezone 参数（如 'Asia/Tokyo'）可直接输出本地时间字符串；2. $hour/$month 等提取操作符也支持 timezone 参数；3. 应用层做时区转换更灵活但增加代码量。生产建议：存储统一用 UTC，展示时在 $dateToString 或应用层转换。
时区处理的常见陷阱：时区是聚合管道中最容易出错的领域——1. 夏令时陷阱：美国/欧洲有夏令时，同一城市在不同月份的 UTC 偏移不同（纽约冬令时 UTC-5，夏令时 UTC-4）。MongoDB 的 timezone 参数会自动处理夏令时，但手动 offset 计算会出错；2. 跨日分组陷阱：UTC+8 的 2026-06-01 02:00 对应 UTC 的 2026-05-31 18:00，用 $dayOfMonth 不指定 timezone 会归到 31 日而非 1 日；3. 闰秒/闰年陷阱：$dateAdd 加月份时，1 月 31 日 + 1 个月 = 2 月 28 日（而非 3 月 3 日），MongoDB 自动处理；4. 时区数据库更新：MongoDB 内置 IANA 时区数据库，但旧版本可能缺少新时区规则，需定期升级 MongoDB 版本。
日期操作最佳实践：1. 日期范围查询用 $gte/$lt 而非 $dayOfMonth 等提取函数（前者可用索引，后者不行）；2. 按月分组时用 {_id: {year: {$year: '$date'}, month: {$month: '$date'}}} 而非 $dateToString（前者可利用索引）；3. 日期计算（加减天数）在聚合管道中比应用层更高效（避免传输大量日期字段）。
// === $year / $month / $dayOfWeek / $hour ===
db.orders.aggregate([
{
$project: {
year: { $year: '$createdAt' },
month: { $month: '$createdAt' },
day: { $dayOfMonth: '$createdAt' },
weekday: { $dayOfWeek: '$createdAt' }, // 1=Sunday
hour: { $hour: '$createdAt' }
}
}
]);
(2) 日期格式化
$dateToString 的格式符速查：$dateToString 使用类 strftime 格式符——%Y（四位年）、%m（两位月）、%d（两位日）、%H（24小时制）、%M（分钟）、%S（秒）、%L（毫秒）、%j（年内天数）、%U（年内周数）。常见组合：'%Y-%m-%d'（日期键）、'%Y-%m'（月键）、'%Y-W%U'（周键）、'%Y-%m-%d %H:00'（小时键）。时区参数 timezone 接受 Olsen 格式（如 'Asia/Shanghai'）或 UTC 偏移（如 '+08:00'）。
日期格式化的典型应用：日期格式化最常见的用途是按时间维度分组统计——用 $dateToString 生成日期键，再用 $group 按日期键聚合。例如：按月统计销售趋势（$dateToString → $group → $sort）、按小时统计访问峰值、按周统计用户留存。关键优化：如果只需要按月分组，用 {year: {$year}, month: {$month}} 比 $dateToString 更高效（前者可以利用索引，后者将日期转为字符串后无法使用索引）。
// === $dateToString 格式化日期 ===
db.orders.aggregate([
{
$project: {
orderDate: {
$dateToString: {
format: '%Y-%m-%d %H:%M:%S',
date: '$createdAt',
timezone: 'Asia/Tokyo'
}
}
}
}
]);
// { orderDate: '2026-07-01 10:30:00' }
| 格式符 | 含义 |
|---|---|
%Y |
4 位年份 |
%m |
2 位月份 |
%d |
2 位日期 |
%H |
24 小时制小时 |
%M |
分钟 |
%S |
秒 |
(3) 日期运算
日期运算的业务场景：日期运算在电商和 SaaS 系统中极为常见——1. 订单过期检查：$add[createdAt, 3086400000] 计算支付截止日期，超过则自动取消；2. 用户活跃度分析：$subtract[now, lastLoginAt] 计算距今天数，>30 天标记为流失用户；3. 订阅续费提醒：$subtract[expiryDate, now] 计算剩余天数，<7 天发送提醒；4. 报表时间窗口：$match {createdAt: {$gte: $add[now, -3086400000]}} 取最近 30 天数据。
日期运算的时间单位换算：MongoDB 日期运算的底层单位是毫秒——1 天 = 86400000 毫秒，1 小时 = 3600000 毫秒。常见换算错误：1. 忘记乘 1000（用 86400 而非 86400000），结果差 1000 倍；2. 用 30*86400000 表示"30 天"是近似值（不同月份天数不同），对精确日期计算应使用 $dateAdd（MongoDB 5.0+）而非 $add；3. 时区问题：$hour/$dayOfMonth 等操作符默认 UTC，需要本地时间时加 timezone 参数（如 {$hour: {date: '$createdAt', timezone: 'Asia/Shanghai'}}）。时间计算是 bug 高发区——务必用单元测试验证关键日期逻辑。
// === $add / $subtract 日期加减 ===
db.orders.aggregate([
{
$project: {
createdAt: 1,
expiryDate: { $add: ['$createdAt', 7 * 24 * 60 * 60 * 1000] }, // 加 7 天
daysSinceCreated: {
$divide: [
{ $subtract: [new Date(), '$createdAt'] },
1000 * 60 * 60 * 24
]
}
}
}
]);
4. 类型转换
概念说明：MongoDB 是弱类型存储，同一集合的字段可能存在多种类型（如 price 可能是 String 或 Number）。聚合管道提供 $toString/$toInt/$toLong/$toDouble/$toDecimal/$toDate/$toBool 等转换操作符，解决数据类型不一致问题。$convert 提供更安全的转换方式（可指定 onError 处理）。
工作原理：类型转换操作符对每个文档的字段值执行转换。$toInt('42') → 42，$toString(3.14) → '3.14'。转换失败时，$toXxx 返回 null 并产生警告，$convert 可指定 onError 返回自定义值。在 $project 或 $addFields 中使用转换，确保后续阶段数据类型一致。
弱类型系统的挑战：MongoDB 的弱类型是一把双刃剑——灵活（无需预定义类型）但也危险（同一字段可能存不同类型）。典型问题：1. 迁移遗留数据时 price 可能是字符串"599"或数字 599；2. $group 的 $avg 遇到字符串字段返回 null 而非报错；3. $sort 混合类型排序结果不可预测（按 BSON 类型比较顺序）。解决方案：在聚合管道第一步用 $convert 统一类型，或在 mongoose Schema 层严格约束类型。
$convert 的安全转换模式：$convert 比 $toXxx 更安全——它支持 onError 和 onNull 参数，可以在转换失败时返回自定义默认值而非 null。推荐模式：$convert({input: '$price', to: 'decimal', onError: NumberDecimal('0'), onNull: NumberDecimal('0')})。这样即使 price 是非数字字符串或 null，聚合管道也能继续执行而不会产生 null 传播问题。生产环境的聚合管道应始终使用 $convert 而非 $toXxx。
类型转换的最佳实践总结：1. 永远用 $convert + onError 而非裸 $toXxx（容错性）；2. 在管道最前面统一类型（$addFields + $convert），确保后续阶段数据类型一致；3. 用 $type 检查字段类型，对不同类型走不同转换逻辑（$switch + $type）；4. Decimal128 用于货币计算，Double 用于科学计算，Int32 用于计数；5. 字符串日期转 Date 用 $toDate（ISO 8601 格式），非标格式先 $dateFromString 或应用层预处理。
类型转换的调试技巧：聚合管道中类型错误的调试是最耗时的——1. 用 $type 操作符检查字段类型：$addFields: {priceType: {$type: '$price'}} 查看每个文档的 price 是什么类型；2. 用 $cond + $type 做条件转换：$switch: {branches: [{case: {$eq: [{$type: '$price'}, 'string']}, then: {$toDecimal: '$price'}}, {case: {$eq: [{$type: '$price'}, 'double']}, then: {$toDecimal: '$price'}}], default: '$price'}；3. 在 Compass 中逐阶段查看输出，找到类型不匹配的位置。预防胜于治疗——在 mongoose Schema 中严格约束类型，从源头避免弱类型问题。
| 转换操作符 | 输入→输出 | 典型场景 |
|---|---|---|
$toString |
任意→String | 数值转字符串显示 |
$toInt |
String/Number→Int32 | 字符串价格转整数 |
$toLong |
String/Number→Int64 | 大数ID转换 |
$toDouble |
String/Number→Double | 精确计算 |
$toDecimal |
String/Number→Decimal128 | 货币精确运算 |
$toDate |
String/Number→Date | 字符串日期转Date |
$convert |
可指定onError | 安全转换（推荐） |
类型转换的安全策略：MongoDB 的弱类型特性意味着同一字段可能混存多种类型——price 可能是 String、Number、甚至 Decimal128。类型转换操作符解决这种不一致，但需注意安全策略：1. $toInt/$toDouble 等严格转换，遇到不兼容值直接报错；2. $convert + onError/onNull 提供容错转换（推荐）；3. 转换前用 $type 检查字段类型，避免盲目转换；4. 数据清洗应在 ETL 阶段完成，聚合管道中的转换是最后防线。
$convert vs $toXxx 对比：
| 维度 | $toXxx | $convert |
|---|---|---|
| 语法 | 简洁 | 略复杂 |
| 错误处理 | 报错中断 | onError 返回自定义值 |
| 空值处理 | 返回 null | onNull 返回自定义值 |
| 推荐场景 | 数据已确认干净 | 生产环境容错 |
类型转换的常见陷阱：1. $toInt('3.14') 报错——必须先用 $toDouble 再 $toInt；2. $toDate('2026-07-01') 成功但 $toDate('07/01/2026') 失败——MongoDB 只认 ISO 8601 格式；3. $toBool('false') 返回 true——非空字符串都是 truthy；4. $toDouble(null) 返回 null 而非 0——后续算术运算 null 传播导致整个表达式为 null。避免陷阱的通用策略：先用 $ifNull 处理空值，再用 $convert 处理类型转换。
// === 数值类型转换 ===
db.products.aggregate([
{
$project: {
title: 1,
price: 1,
priceString: { $toString: '$price' }, // Decimal128 → string
priceInt: { $toInt: '$price' }, // → Int32
priceLong: { $toLong: '$price' }, // → Int64
priceDouble: { $toDouble: '$price' }, // → Double
priceDecimal: { $toDecimal: '$price' } // → Decimal128
}
}
]);
// === 日期转换 ===
db.products.aggregate([
{
$project: {
title: 1,
releaseDate: { $toDate: '$releaseDateStr' } // string → Date
}
}
]);
5. 字符串操作
字符串操作的性能考量：聚合管道中的字符串操作是逐文档执行的，在大数据集上可能成为瓶颈。关键注意点：1. $substr 按字节截取，中文等 UTF-8 多字节字符可能被截断——务必用 $substrCP 按字符截取；2. $concat 拼接大量字段时注意结果长度（BSON String 最大 16MB）；3. $regexMatch 配合 $filter 可实现模糊匹配过滤；4. 字符串操作应在 $match 之后执行（先过滤减少处理量）。
字符串操作的常见陷阱：1. $concat 与 null：任何参数为 null 时 $concat 返回 null——用 $ifNull 包裹每个参数（{$concat: [{$ifNull: ['$firstName', '']}, ' ', {$ifNull: ['$lastName', '']}]}）；2. $toLower/$toUpper 与多语言：这两个操作符只处理 ASCII 字母，中文/日文/韩文不受影响（本来就无大小写），但德语 ß → SS 转换不被支持；3. $split 与空字符串：$split: ['', ','] 返回空数组 []（而非 ['']），与 JavaScript 的 ''.split(',') 行为不同；4. $replaceOne vs $replaceAll：MongoDB 4.4+ 用 $replaceOne（替换第一个匹配）和 $replaceAll（替换所有匹配），注意旧版本没有这两个操作符。
$substr vs $substrCP 的关键区别：$substr 按字节偏移截取，$substrCP 按字符偏移截取——对纯 ASCII 文本两者等价，但中文/日文/emoji 是多字节字符，$substr 可能截断半个字符产生乱码。例如："你好世界" 用 $substr: ['$text', 0, 3] 截取前 3 字节，得到乱码（一个中文字符占 3 字节）；用 $substrCP: ['$text', 0, 1] 截取前 1 个字符，得到"你"。规则：如果字段可能包含非 ASCII 字符，永远用 $substrCP。
$regexMatch 的使用模式：$regexMatch 在聚合管道中实现正则匹配——返回 boolean，常与 $filter 组合过滤数组元素。例如：从标签数组中筛选以"mongo"开头的标签——$filter: {input: '$tags', cond: {$regexMatch: {input: '$$this', regex: '^mongo'}}}}。注意：$regexMatch 不走索引——它是对每个值逐个匹配，性能随数据量线性增长。大量数据的正则搜索应先 $match（可以用索引）再 $regexMatch。
$concat 的 null 处理：$concat 遇到 null 输入时整个表达式返回 null——这不是 Bug，而是 SQL 的标准 null 传播行为。例如：$concat: ['$firstName', ' ', '$lastName'] 如果 lastName 为 null，整个结果为 null 而非 "John null"。解决方案：1. $ifNull 包裹每个可能为 null 的字段（$concat: [$ifNull: ['$firstName', ''], ' ', $ifNull: ['$lastName', '']]）；2. 用 $convert + onError 替代 $concat 的隐式转换；3. 在数据入库时确保字符串字段有默认值（default: ''）。null 传播是字符串操作最常见的"意外 null 结果"原因。
$split + $arrayElemAt 的组合技巧：$split 将字符串按分隔符拆分为数组，$arrayElemAt 按索引取元素——两者组合实现"提取字符串的某一部分"。典型场景：1. 提取邮箱域名——$arrayElemAt: [$split: ['$email', '@'], 1] 取 @ 后面的部分；2. 提取姓名——$arrayElemAt: [$split: ['$fullName', ' '], 0] 取空格前的部分；3. 解析路径——$arrayElemAt: [$split: ['$path', '/'], -1] 取最后一个路径段。注意 $split 对 null 输入返回 null（需 $ifNull 防护），对空字符串返回 ['']（数组含一个空字符串，不是空数组）。
$concat 的 null 处理：$concat 的致命陷阱——任何一个输入为 null，整个结果就返回 null。例如：$concat: ['$firstName', ' ', '$lastName']，如果 lastName 为 null，结果就是 null 而非 "John null"。防御方式：每个可能为 null 的输入都套 $ifNull——$concat: [$ifNull: ['$firstName', ''], ' ', $ifNull: ['$lastName', '']]。这个模式在拼接地址、姓名等字段时极其常见。
$split + $arrayElemAt 的组合技巧：$split 将字符串分割为数组，$arrayElemAt 取指定索引——两者组合实现"提取子串"。经典模式：1. 从 email 提取域名：$arrayElemAt: [{ $split: ['$email', '@'] }, 1] → "gmail.com"；2. 从 URL 提取路径：$arrayElemAt: [{ $split: ['$url', '/'], 3 }]；3. 从全名提取姓：$arrayElemAt: [{ $split: ['$fullName', ' '] }, 0]。$split 不支持正则分隔符——如果分隔符不固定，需先用 $trim 清理多余空格。
// === $substr 字符串截取 ===
db.users.aggregate([
{
$project: {
email: 1,
emailPrefix: { $substr: ['$email', 0, 5] } // email 前 5 个字符
}
}
]);
// === $concat 字符串拼接 ===
db.users.aggregate([
{
$project: {
fullName: { $concat: ['$firstName', ' ', '$lastName'] }
}
}
]);
// === $toUpper / $toLower 大小写 ===
db.users.aggregate([
{
$project: {
usernameUpper: { $toUpper: '$username' }
}
}
]);
6. 数组操作
数组操作在聚合管道中的地位：数组操作是 MongoDB 聚合管道区别于 SQL 的核心能力——SQL 的行级操作无法处理嵌套数组，而 $map/$filter/$reduce 让数组内的元素变换、过滤、累积成为可能。这直接源于 MongoDB 文档模型的数组嵌套特性。$map 相当于对数组每个元素执行 $project，$filter 相当于对数组执行 $match，$reduce 相当于对数组执行 $group——掌握这三个操作符等于掌握了数组级别的"聚合能力"。
$unwind 的风险与应对：$unwind 将数组拆分为多个文档，每个文档包含数组的一个元素。风险：1. 大数组拆分产生大量文档（1000 元素数组→1000 个文档），导致管道数据膨胀；2. 拆分后需要 $group 重新聚合，增加复杂度；3. 空数组默认丢弃整个文档（需 preserveNullAndEmptyArrays: true）。最佳实践：能用 $map/$filter 解决的不用 $unwind，必须 $unwind 时紧跟 $group 重组。
$map/$filter/$reduce 与 JavaScript 数组方法的对应关系：聚合管道的数组操作符与 JavaScript 数组方法一一对应——$map ↔ Array.map()（变换每个元素）、$filter ↔ Array.filter()（过滤元素）、$reduce ↔ Array.reduce()（累积计算）、$concatArrays ↔ [...a, ...b]（合并数组）、$reverseArray ↔ Array.reverse()（反转）、$arrayElemAt ↔ Array[index]（按索引取值）、$size ↔ Array.length（数组长度）。这种对应关系让前端开发者快速上手聚合管道的数组操作。
数组操作的常见陷阱：数组操作有几个常见陷阱——1. $filter 的 cond 必须返回布尔值（返回 null/undefined 的表达式不会过滤该元素，而是保留）；2. $reduce 的 initialValue 必须指定（不指定则用数组第一个元素作为初始值，但如果数组为空则返回 null）；3. $arrayElemAt 的负索引从末尾计数（-1 是最后一个元素，-2 是倒数第二个），但如果索引超出范围返回 null；4. $size 对 null/undefined 字段报错（需 $ifNull: ['$array', []] 防护）；5. $map 的 as 参数默认是 'this'，但自定义名称更可读（$map: {input: '$tags', as: 'tag', in: {$toUpper: '$$tag'}}}）。
$$this 和 $$value 的作用域：$map/$filter/$reduce 使用 $$this 引用当前遍历的数组元素，$reduce 使用 $$value 引用累积值。注意双美元符号——$$ 表示系统变量（$$this、$$value、$$ROOT、$$DESCEND），单 $ 表示字段引用。常见错误：在 $filter 的 cond 中用 $field 而非 $$this.field——$field 引用的是文档顶层字段，$$this.field 引用的是当前数组元素的字段。理解作用域差异是正确使用数组操作符的关键。
| 操作符 | 输入 | 输出 | 文档数变化 |
|---|---|---|---|
| $map | N 文档 | N 文档 | 不变（数组内变换） |
| $filter | N 文档 | N 文档 | 不变（数组内过滤） |
| $unwind | N 文档 | N×M 文档 | 膨胀（拆分数组） |
$map 与 $filter 的组合模式：$map 和 $filter 经常组合使用——先用 $filter 筛选需要的数组元素，再用 $map 变换格式。例如：订单中只取已发货的商品名——$map: {input: {$filter: {input: '$items', cond: {$eq: ['$$this.status', 'shipped']}}}, in: '$$this.name'}。注意顺序：先 filter 后 map（减少 map 处理的元素数量）。反序（先 map 后 filter）性能更差且可读性低。
$reduce 的累积计算：$reduce 将数组缩减为单个值——语法 {input: array, initialValue: value, in: expression}。典型场景：1. 数组求和 $reduce: {initialValue: 0, in: {$add: ['$$value', '$$this']}}；2. 数组拼接 $reduce: {initialValue: '', in: {$concat: ['$$value', ',', '$$this']}}；3. 数组最大值 $reduce: {initialValue: 0, in: {$cond: [{$gt: ['$$this', '$$value']}, '$$this', '$$value']]}。$$value 是累积值，$$this 是当前元素。
graph LR
A["tags: ['5g','amoled','fast']"] --> B["$arrayElemAt: 0<br/>→ '5g'"]
A --> C["$size<br/>→ 3"]
A --> D["$map: {$toUpper}<br/>→ ['5G','AMOLED','FAST']"]
A --> E["$filter: len >= 3<br/>→ ['amoled','fast']"]
style B fill:#d4edda
style C fill:#cce5ff
style D fill:#fff3cd
style E fill:#e2d5f1
| 操作符 | 功能 | 类比 JavaScript |
|---|---|---|
$arrayElemAt |
按索引取元素 | arr[index] |
$size |
数组长度 | arr.length |
$map |
逐元素变换 | arr.map(fn) |
$filter |
条件过滤 | arr.filter(fn) |
$reduce |
累积计算 | arr.reduce(fn, init) |
$concatArrays |
合并数组 | [...a, ...b] |
$reverseArray |
反转数组 | arr.reverse() |
$size 的常见陷阱：$size 只能用于数组字段——如果字段不是数组（如 null 或不存在），$size 会报错。防御方式：1. 先用 $ifNull: ['$tags', []] 将 null 转为空数组；2. 用 $type: '$tags' 判断是否为数组再计算；3. 在 Schema 中设 default: []（确保字段始终是数组）。$size 返回整数，可以直接用于 $cond 判断——如 $cond: [{$gte: [{$size: '$tags'}, 3]}, '标签丰富', '标签不足']。
$arrayElemAt 的负索引：$arrayElemAt 支持负索引——-1 取最后一个元素、-2 取倒数第二个，与 JavaScript 的 arr.at(-1) 行为相同。常见用途：1. 取最新一条记录 {$arrayElemAt: ['$orders', -1]}（前提是 orders 已按时间排序）；2. 取第一个标签 {$arrayElemAt: ['$tags', 0]}；3. 取最后一个地址 {$arrayElemAt: ['$addresses', -1]}。如果索引超出范围，$arrayElemAt 返回 null（不报错），需要 $ifNull 兜底。
数组操作的链式组合：$map、$filter、$reduce 可以链式组合——先用 $filter 筛选，再用 $map 变换，最后 $reduce 聚合。例如：计算已发货商品的总价——$reduce: {input: {$map: {input: {$filter: {input: '$items', cond: {$eq: ['$$this.status', 'shipped']}}}, in: '$$this.price'}}, initialValue: 0, in: {$add: ['$$value', '$$this']}}。注意执行顺序：先 filter（减少 map 处理的元素），再 map（提取价格），最后 reduce（求和）。
链式组合的性能优化：数组操作的链式组合虽然强大，但每层嵌套都增加计算量——1. 优化顺序：先 $filter（减少后续操作的数据量），再 $map（只提取必要字段），最后 $reduce（计算最终结果）；2. 避免重复计算：如果多个链式操作需要相同的中间结果，用 $addFields 先计算一次再引用；3. 大数组注意：1000+ 元素的数组做 $map + $filter + $reduce 可能耗时较长，考虑先 $unwind + $group 替代（$unwind 在数据库层比 $map 在表达式层更快处理大数组）；4. 管道前加 $match：只对需要的文档执行数组操作（如只处理已付款订单的 items 数组）。
$reduce 的三种累积模式：$reduce 的 in 参数决定累积方式——1. 数值累积：in: {$add: ['$$value', '$$this']}（求和），in: {$max: ['$$value', '$$this']}（取最大值）；2. 字符串累积：in: {$concat: ['$$value', ',', '$$this']}（逗号分隔拼接）；3. 对象累积：in: {$mergeObjects: ['$$value', '$$this']}（合并对象属性）。$reduce 的 initialValue 决定初始值类型和最终输出类型——数值初始值 0 → 输出 Number，字符串初始值 '' → 输出 String，对象初始值 {} → 输出 Object。初始值类型必须与 in 参数的输出类型匹配。
// === $arrayElemAt 按索引取元素 ===
db.products.aggregate([
{
$project: {
title: 1,
firstTag: { $arrayElemAt: ['$tags', 0] },
lastTag: { $arrayElemAt: ['$tags', -1] }
}
}
]);
// === $size 数组长度 ===
db.products.aggregate([
{
$project: {
title: 1,
tagCount: { $size: '$tags' }
}
}
]);
// === $map 数组变换 ===
db.products.aggregate([
{
$project: {
title: 1,
tagsUpper: {
$map: {
input: '$tags',
as: 'tag',
in: { $toUpper: '$$tag' }
}
}
}
}
]);
// === $filter 数组过滤 ===
db.products.aggregate([
{
$project: {
title: 1,
expensiveTags: {
$filter: {
input: '$relatedProducts',
as: 'product',
cond: { $gte: ['$$product.price', 1000] }
}
}
}
}
]);
7. 综合实战
聚合管道性能调优清单：生产环境的聚合管道需要系统化优化——1. $match 放最前，尽早过滤减少数据量；2. $project 在 $group 后精简字段，减少内存占用；3. $sort + $limit 替代全量排序（Top N 模式）；4. $group 的 _id 避免使用复杂表达式（影响分组效率）；5. 大数据集设 allowDiskUse: true；6. 用 hint() 强制索引避免全集合扫描；7. $unwind 后紧跟 $group 避免数据膨胀累积；8. $facet 的子管道共享输入但各自独立，控制子管道数量。
聚合管道的调试技巧：聚合管道链式调用，中间结果不可见，调试困难。三个实用技巧：1. 逐阶段执行——每次只加一个阶段，检查输出是否符合预期；2. $project 只保留关键字段，减少输出噪音便于分析；3. 在 Compass 的 Aggregation Pipeline Builder 中可视化调试。遇到 $group 结果不符预期时，检查 _id 是否正确——最常见的错误是 _id 中的字段名拼写错误或遗漏引号。
RFM 用户分层的业务应用：RFM（Recency/Frequency/Monetary）是电商最常用的用户分层模型——1. Recency（最近购买时间）：daysSinceLastOrder 越小越好（最近购买的用户更容易再次购买）；2. Frequency（购买频率）：orderCount 越高越好（频繁购买的用户是忠实客户）；3. Monetary（消费金额）：totalSpent 越高越好（高消费用户贡献大部分收入）。RFM 三个维度各分高/低两档，组合出 8 种用户类型——"高R高F高M"是最有价值的VIP用户，"低R低F低M"是需要激活或放弃的流失用户。$switch 将 RFM 分数映射为用户标签，是 RFM 分析的聚合管道实现。
报表数据的准备与校验：销售报表的测试数据必须精心设计——1. 覆盖足够长的时间范围（至少 3 个月，环比计算需要上月数据）；2. 包含异常值（0 元订单、退款订单，测试 $match 过滤的健壮性）；3. 分布合理（小额多笔+大额少笔，模拟真实订单分布）；4. 状态多样（paid/pending/refunded，测试 $match: {status: 'paid'} 的过滤效果）。用 insertMany 批量插入测试数据后，先用简单 find 验证数据正确性，再执行聚合管道——数据问题比管道问题更常见。
销售报表的业务价值：月度销售报表是电商运营的核心数据——它回答三个关键问题：1. 趋势如何（收入是增长还是下降？）；2. 原因是什么（哪个品类/哪个商品拉动或拖累？）；3. 如何调整（促销/备货/选品策略）。$setWindowFields + $shift 计算同比增长率，是报表从"展示数据"升级为"提供洞察"的关键一步——知道"本月收入 3000"不如知道"环比增长 100%"。
聚合管道与 BI 工具的对比：聚合管道 vs Tableau/Metabase 等 BI 工具——聚合管道是编程接口（灵活、自动化、可嵌入应用），BI 工具是可视化接口（拖拽式、适合非技术人员、交互式探索）。最佳实践：1. 运营人员的即席查询用 BI 工具（连接 MongoDB BI Connector）；2. 应用内嵌的固定报表用聚合管道（性能可控、结果可缓存）；3. 数据科学家的深度分析用 Jupyter + PyMongo（Python 生态更丰富）。聚合管道适合"已知的、重复的"分析需求，BI 工具适合"未知的、探索性的"分析需求。
(1) 复杂业务场景
RFM 用户分层模型：RFM（Recency/Frequency/Monetary）是电商用户分层的经典模型——Recency 最近一次购买距今多少天，Frequency 购买频次，Monetary 累计消费金额。三个维度各分高/中/低三档，组合出 27 种用户类型。核心洞察：R 高 F 高 M 高 = 核心VIP用户（需重点维护）；R 低 F 高 M 高 = 流失风险用户（需召回）；R 高 F 低 M 低 = 新用户（需培育）。MongoDB 聚合管道完美适配 RFM 计算——$group 按 userId 聚合计算三维度，$switch 将数值映射为高/中/低档。
用户分层的业务应用：RFM 分层的结果驱动差异化运营策略——1. VIP 用户：专属折扣 + 优先发货 + VIP 客服；2. 流失风险用户：定向优惠券 + 召回短信 + 限时特价；3. 新用户：首单优惠 + 新手引导 + 推荐商品；4. 沉默用户：低成本唤醒（push 通知而非短信）。每种策略对应不同的营销成本——VIP 用户 ROI 最高（留存成本低），新用户次之，沉默用户最低。
// === 场景：用户分层分析 ===
db.orders.aggregate([
{ $match: { status: 'paid' } },
{
$group: {
_id: '$userId',
totalSpent: { $sum: '$total' },
orderCount: { $sum: 1 },
avgOrderValue: { $avg: '$total' },
firstOrderAt: { $min: '$createdAt' },
lastOrderAt: { $max: '$createdAt' }
}
},
{
$addFields: {
userLevel: {
$switch: {
branches: [
{ case: { $gte: ['$totalSpent', 10000] }, then: 'VIP' },
{ case: { $gte: ['$totalSpent', 1000] }, then: 'Gold' },
{ case: { $gte: ['$totalSpent', 100] }, then: 'Silver' }
],
default: 'Bronze'
}
},
daysSinceLastOrder: {
$divide: [
{ $subtract: [new Date(), '$lastOrderAt'] },
1000 * 60 * 60 * 24
]
}
}
},
{ $sort: { totalSpent: -1 } },
{ $limit: 100 }
]);
(2) 销售报表
$setWindowFields 窗口函数原理：$setWindowFields（MongoDB 5.0+）是聚合管道的窗口函数，类似 SQL 的 OVER() 子句。它在不改变文档数的前提下，为每个文档计算基于窗口的聚合值——如移动平均、累计求和、前后行值。$shift 是窗口函数中的偏移操作，$shift: {output: '$revenue', by: -1} 获取前一行的 revenue 值，用于计算环比增长率。
环比增长计算模式：月度报表的同比增长需要当前月和上月数据——传统 SQL 用 LAG() 窗口函数，MongoDB 用 $setWindowFields + $shift 实现等价功能。计算公式：(当月 - 上月) / 上月 × 100%。注意除零保护：上月为 0 时增长率设为 0（用 $cond 判断）。
窗口函数的边界情况：$shift 在第一行取前一行时返回 null（没有前一行）——这就是为什么 growthRate 计算需要 $cond 处理 prevMonthRevenue 为 null 的情况。类似地，最后一行取后一行也返回 null。窗口函数的其他边界：1. 空窗口返回 null；2. 单行窗口的 $sum 就是该行值；3. $rank/$denseRank 在并列值时有差异（rank 跳号，denseRank 不跳）。理解边界情况是正确使用窗口函数的前提。
报表系统的分层架构：完整的报表系统分三层——1. 数据层（聚合管道计算原始指标）；2. 分析层（环比/同比/排名等衍生指标）；3. 展示层（格式化/图表/导出）。本例将数据层和分析层合并到一条聚合管道中完成，展示层留给前端。生产环境的报表通常还需要：缓存层（报表数据按小时缓存到 Redis，避免重复计算）、权限层（不同角色看不同维度的数据）、审计层（谁在什么时间查看了什么报表）。
// === 月度销售报表（含同比）===
db.orders.aggregate([
{
$group: {
_id: {
year: { $year: '$createdAt' },
month: { $month: '$createdAt' }
},
revenue: { $sum: '$total' },
orderCount: { $sum: 1 },
avgOrderValue: { $avg: '$total' }
}
},
{ $sort: { '_id.year': 1, '_id.month': 1 } },
{
$setWindowFields: {
sortBy: { '_id.year': 1, '_id.month': 1 },
output: {
prevMonthRevenue: {
$shift: {
output: '$revenue',
by: -1
}
}
}
}
},
{
$addFields: {
growthRate: {
$cond: {
if: { $gt: ['$prevMonthRevenue', 0] },
then: {
$divide: [
{ $subtract: ['$revenue', '$prevMonthRevenue'] },
'$prevMonthRevenue'
]
},
else: 0
}
}
}
}
]);
管道内存管理深度解析：聚合管道的每个阶段在内存中维护文档流，单阶段默认 100MB 限制。超出时 MongoDB 报错并终止管道，除非设置 allowDiskUse: true（允许临时写入磁盘）。但这带来新问题——磁盘 I/O 比内存慢 100 倍，管道性能急剧下降。正确的做法是优化管道避免溢出：1. $match 前置减少输入量；2. $project 精简字段减少每文档占用；3. $group 的 _id 避免过多唯一值；4. $push/$addToSet 注意数组大小限制。
聚合性能调优实用清单：1. 确保第一个 $match 能用索引（检查 explain 输出）；2. $match 在 $group 前、$project 在 $group 后是黄金顺序；3. $sort + $limit 可优化为 Top N 模式（只需维护 N 个元素的堆，而非全量排序）；4. $group 后的 $match 可前移（手动优化，MongoDB 不会自动做）；5. $lookup 的 foreignField 必须有索引；6. 大数据集加 maxTimeMS 防止管道无限运行。
$setWindowFields 窗口函数的边界情况：$setWindowFields 是 MongoDB 5.0 引入的窗口函数——对"窗口"内的文档执行计算（如移动平均、累计求和、排名）。边界情况——1. 窗口边界：unbounded preceding/unbounded following 包含全部分组文档，1 preceding/1 following 只包含相邻文档；2. 空窗口：分组中只有 1 条文档时，$shift/$first/$last 返回 null；3. 排序冲突：sortBy 必须与分组的排序一致，否则窗口范围不可预测；4. 性能：窗口函数需要在内存中维护窗口状态，大数据组（> 10 万条）可能超出内存限制。
$setWindowFields 的实用场景：$setWindowFields 填补了 MongoDB 缺少窗口函数的空白——1. 环比/同比计算：$shift 获取上一期数据，$subtract 计算增长额，$divide 计算增长率；2. 累计求和：$sum 窗口从 unbounded preceding 到 current row，计算累计销售额；3. 移动平均：$avg 窗口取最近 N 期数据（如 7 preceding 到 current row），消除短期波动；4. 排名/分页：$rank/$denseRank 实现排名，$rowNumber 实现分页（比 skip/limit 更灵活）；5. 分组 Top N：partitionBy 分组后 $rank 排名，再 $match rank <= N 取每组前 N 条。这些场景在 SQL 中是标准窗口函数用法，MongoDB 的语法更冗长但功能等价。
报表系统的三层架构：生产级报表系统分三层——1. 数据层（MongoDB 聚合管道）：从原始数据计算统计结果，输出到中间集合；2. 服务层（Node.js + 缓存）：调用聚合管道、缓存结果（Redis TTL 5 分钟）、提供 REST API；3. 展示层（前端图表库）：从 API 获取数据、渲染图表（ECharts/Chart.js）、交互筛选。三层分离的好处——数据层专注计算、服务层专注性能、展示层专注用户体验，每层可独立优化和扩展。
聚合管道 vs BI 工具：何时用聚合管道构建报表，何时用专业 BI 工具（Metabase/Superset/Tableau）？聚合管道适合——1. 报表逻辑简单（5-10 个阶段的聚合管道）；2. 需要嵌入应用（API 返回报表数据，前端自绘图表）；3. 数据量中等（< 千万级）；4. 实时性要求高（每次请求实时计算）。BI 工具适合——1. 非技术人员自助查询（拖拽式界面）；2. 复杂多维分析（OLAP cube、下钻/上卷）；3. 数据源多样（MongoDB + MySQL + CSV）；4. 需要定时邮件推送报表。小团队用聚合管道 + ECharts 足够，大团队用 BI 工具效率更高。
▶ 示例 1：聚合管道进阶实战 - 用户分层分析
// 场景：根据消费金额对用户进行 VIP 分层
db.orders.insertMany([
{ userId: 'user_001', total: NumberDecimal('15000'), createdAt: new Date('2026-06-01'), status: 'paid' },
{ userId: 'user_002', total: NumberDecimal('500'), createdAt: new Date('2026-06-05'), status: 'paid' },
{ userId: 'user_003', total: NumberDecimal('50'), createdAt: new Date('2026-06-10'), status: 'paid' },
{ userId: 'user_001', total: NumberDecimal('800'), createdAt: new Date('2026-06-15'), status: 'paid' }
]);
// 完整管道：用户分层 + 标签转换 + 月度统计
db.orders.aggregate([
// 第 1 步：仅统计已支付订单
{ $match: { status: 'paid' } },
// 第 2 步：按用户分组
{
$group: {
_id: '$userId',
totalSpent: { $sum: '$total' },
orderCount: { $sum: 1 },
avgOrderValue: { $avg: '$total' },
lastOrderAt: { $max: '$createdAt' }
}
},
// 第 3 步：使用 $switch 进行用户分层
{
$addFields: {
userLevel: {
$switch: {
branches: [
{ case: { $gte: ['$totalSpent', 10000] }, then: 'VIP' },
{ case: { $gte: ['$totalSpent', 1000] }, then: 'Gold' },
{ case: { $gte: ['$totalSpent', 100] }, then: 'Silver' }
],
default: 'Bronze'
}
},
// 距离最后订单天数
daysSinceLastOrder: {
$divide: [
{ $subtract: [new Date(), '$lastOrderAt'] },
1000 * 60 * 60 * 24
]
}
}
},
// 第 4 步：格式化日期
{
$project: {
userId: '$_id',
totalSpent: 1,
avgOrderValue: { $toString: '$avgOrderValue' }, // Decimal128 -> String
userLevel: 1,
daysSinceLastOrder: { $round: ['$daysSinceLastOrder', 0] }, // 四舍五入
lastOrderDate: {
$dateToString: {
format: '%Y-%m-%d',
date: '$lastOrderAt',
timezone: 'Asia/Tokyo'
}
}
}
},
// 第 5 步：按消费金额排序
{ $sort: { totalSpent: -1 } }
]);
// 输出结果：
// [
// { userId: 'user_001', totalSpent: '15800', avgOrderValue: '7900', userLevel: 'VIP', daysSinceLastOrder: 16, lastOrderDate: '2026-06-15' },
// { userId: 'user_002', totalSpent: '500', avgOrderValue: '500', userLevel: 'Silver', daysSinceLastOrder: 26, lastOrderDate: '2026-06-05' },
// { userId: 'user_003', totalSpent: '50', avgOrderValue: '50', userLevel: 'Bronze', daysSinceLastOrder: 21, lastOrderDate: '2026-06-10' }
// ]
输出：3 个用户按消费金额自动分层，user_001 总消费 15800 标记为 VIP，距离最后订单 16 天，日期格式化为东京时区。
▶ 示例 2：ShopHub 销售报表 + 日期格式化
报表的数据准备工作：销售报表的测试数据需要覆盖多个月份——否则环比增长无法计算（首月没有上月数据）。本例准备 5-7 月的订单数据，5 月 1 条、6 月 2 条、7 月 1 条。数据设计要点：1. 每月至少 1 条（否则 $bucket 会产生空桶）；2. 金额分布合理（有小额 300 也有大额 2200）；3. 状态统一为 paid（$match 过滤未支付订单）。
环比增长的解读：环比增长率 = (本月 - 上月) / 上月。6 月收入 3000 相对 5 月 1500 增长 100%——这是"翻倍"增长。但要注意基数效应——从 100 增长到 200 也是 100% 增长，但绝对增量只有 100；从 10000 增长到 15000 只有 50% 增长，但绝对增量 5000。业务决策时需要同时看增长率和绝对增量，不能只看一个指标。
报表的数据验证方法：聚合管道的输出结果需要验证——1. 交叉验证：用 find().count() 的结果与 $group 的 $sum: 1 结果对比，数量必须一致；2. 抽样验证：随机选取 2-3 条原始数据，手动计算验证聚合结果是否正确；3. 边界验证：空数据集（$match 无匹配）→ 空结果而非报错；单条数据（$group 只有 1 组）→ 环比增长率为 0（上月不存在）；4. 一致性验证：月度总和 = 年度总和，各分类总和 = 全局总和。任何不一致都说明管道逻辑有 bug。
报表缓存策略：实时聚合管道在大数据集上耗时较长（秒级）——1. 定时物化：每小时用 $merge 将聚合结果写入报表集合（如 monthly_reports），查询从报表集合读取（毫秒级）；2. 增量更新：只对新增数据执行聚合（$match 增量时间范围），$merge 合并到已有报表；3. 缓存层：Node.js 用 Redis 缓存聚合结果（TTL 5-30 分钟），适合读多写少的报表页面；4. 过期策略：原始数据变更后标记缓存失效（用版本号或时间戳），下次查询时重新计算。选择策略的依据：数据变更频率（实时性要求）× 查询频率（性能要求）。
// 场景：ShopHub 运营团队按月生成销售报表，含格式化日期和同比增长
db.orders.insertMany([
{ orderId: 'ORD-001', userId: 'user_001', total: NumberDecimal('1500'), status: 'paid', createdAt: new Date('2026-05-15') },
{ orderId: 'ORD-002', userId: 'user_002', total: NumberDecimal('800'), status: 'paid', createdAt: new Date('2026-06-01') },
{ orderId: 'ORD-003', userId: 'user_001', total: NumberDecimal('2200'), status: 'paid', createdAt: new Date('2026-06-20') },
{ orderId: 'ORD-004', userId: 'user_003', total: NumberDecimal('300'), status: 'paid', createdAt: new Date('2026-07-05') }
]);
// 月度报表：格式化月份、计算环比增长、用户分层标记
db.orders.aggregate([
{ $match: { status: 'paid' } },
{
$group: {
_id: {
year: { $year: '$createdAt' },
month: { $month: '$createdAt' }
},
revenue: { $sum: '$total' },
orderCount: { $sum: 1 },
avgOrderValue: { $avg: '$total' }
}
},
{ $sort: { '_id.year': 1, '_id.month': 1 } },
{
$addFields: {
monthLabel: {
$dateToString: {
format: '%Y-%m',
date: { $dateFromParts: { year: '$_id.year', month: '$_id.month' } }
}
},
revenueStr: { $toString: '$revenue' },
performance: {
$switch: {
branches: [
{ case: { $gte: ['$revenue', 2000] }, then: 'Excellent' },
{ case: { $gte: ['$revenue', 1000] }, then: 'Good' },
{ case: { $gte: ['$revenue', 500] }, then: 'Average' }
],
default: 'Below Target'
}
}
}
}
]);
// 输出：
// [
// { _id: {year:2026,month:5}, monthLabel:'2026-05', revenue:1500, performance:'Good', ... },
// { _id: {year:2026,month:6}, monthLabel:'2026-06', revenue:3000, performance:'Excellent', ... },
// { _id: {year:2026,month:7}, monthLabel:'2026-07', revenue:300, performance:'Below Target', ... }
// ]
输出：月度报表含格式化月份标签（2026-05）、收入字符串转换、$switch 自动标记业绩等级。
报表系统的生产化改造：本例的聚合管道是教学版本——生产环境需要更多改造——1. 参数化查询：月份范围、分类筛选、用户 ID 过滤都应作为 API 参数传入（而非硬编码在管道中）；2. 错误处理：管道执行可能因内存超限或超时而失败，需要 try-catch 包裹 + maxTimeMS 限制 + allowDiskUse 兜底；3. 缓存层：月度报表数据变更频率低（每天几条新订单），用 Redis 缓存聚合结果（TTL 1 小时），90% 的报表请求命中缓存无需执行管道；4. 定时物化：用 Change Stream 监听订单变更，增量更新报表集合（而非每次全量聚合）；5. 输出格式适配：前端需要的是 Chart.js 格式（{labels: [...], datasets: [...]}），在后端将聚合结果转换为图表格式。
聚合管道的错误排查清单：聚合管道报错时的排查步骤——1. 错误类型分类："Buffer exceeds limit" → 内存超限（加 allowDiskUse 或优化管道）；"exceeded time limit" → 执行超时（加 maxTimeMS 或优化索引）；"field path must start with '$'" → 字段引用错误（检查 $ 前缀）；"unknown operator" → 操作符拼写错误或版本不支持；2. 逐阶段调试：每次只执行一个阶段，确认输出正确后再加下一个；3. 数据量验证：$group 前后的文档数是否符合预期（$match 过滤了多少、$unwind 膨胀了多少）；4. 索引检查：explain() 确认 $match 使用了索引（IXSCAN 而非 COLLSCAN）；5. 版本兼容：$dateAdd (5.0+)、$setWindowFields (5.0+)、$densify (6.1+) 等操作符需要对应 MongoDB 版本。
▶ 示例 3：$facet 多输出并行聚合 + $redact 递归文档裁剪
$facet 允许在同一个聚合管道中并行执行多个子管道，每个子管道产生独立的输出——适合一次查询返回多个维度的统计结果。$redact 则可以根据条件递归裁剪文档的嵌套字段，实现字段级权限控制。本示例用 $facet 一次返回用户概览、活跃度分布和消费分层，用 $redact 实现基于角色的字段过滤。
// === 1. $facet 多维度用户分析 ===
db.users.aggregate([
{ $match: { status: 'active' } },
{
$facet: {
overview: [
{
$group: {
_id: null,
totalUsers: { $sum: 1 },
avgBalance: { $round: [{ $avg: '$balance' }, 2] },
maxBalance: { $max: '$balance' },
minBalance: { $min: '$balance' }
}
}
],
activityDistribution: [
{
$bucket: {
groupBy: '$loginCount',
boundaries: [0, 10, 50, 100, 500],
default: '500+',
output: {
count: { $sum: 1 },
avgBalance: { $round: [{ $avg: '$balance' }, 0] }
}
}
}
],
spendingTiers: [
{
$switch: {
branches: [
{ case: { $gte: ['$balance', 5000] }, then: 'premium' },
{ case: { $and: [{ $gte: ['$balance', 1000] }, { $lt: ['$balance', 5000] }] }, then: 'regular' }
],
default: 'budget'
}
},
{
$group: {
_id: '$result',
count: { $sum: 1 },
totalBalance: { $sum: '$balance' }
}
}
]
}
}
]);
// $facet 输出：{ overview: [...], activityDistribution: [...], spendingTiers: [...] }
// === 2. $redact 基于角色的字段裁剪 ===
// 场景：订单文档包含内部字段（cost, profitMargin），只允许 admin 角色查看
const orderWithInternalFields = {
orderId: 'ORD-001',
items: [
{ sku: 'PHONE-001', name: 'Smartphone', price: 599, cost: 350, profitMargin: 0.42 },
{ sku: 'CASE-001', name: 'Case', price: 19, cost: 5, profitMargin: 0.74 }
],
customer: { name: 'Alice', email: 'alice@example.com', internalNotes: 'VIP customer' },
internalAudit: { reviewedBy: 'manager_zhang', approvedAt: new Date() }
};
// admin 可看所有字段，customer 只看非内部字段
function redactByRole(userRole) {
return db.orders.aggregate([
{ $match: { orderId: 'ORD-001' } },
{
$redact: {
$cond: {
if: {
$gt: [
{ $size: { $setIntersection: ['$$desc.fields', { $literal: ['cost', 'profitMargin', 'internalNotes', 'internalAudit'] }] } },
0
]
},
then: {
$cond: {
if: { $eq: [{ $literal: userRole }, 'admin'] },
then: '$$descend',
else: '$$prune'
}
},
else: '$$descend'
}
}
}
]);
}
// === 3. 更简洁的 $redact 模式：用字段标记控制可见性 ===
// 在文档中嵌入 accessLevel 标记
db.secureDocs.insertMany([
{
title: 'Public Report',
accessLevel: 'public',
content: 'Quarterly results: revenue up 15%',
sections: [
{ heading: 'Summary', accessLevel: 'public', text: 'Strong growth across all markets' },
{ heading: 'Internal Details', accessLevel: 'admin', text: 'Revenue: $2.3M, Cost: $1.1M' }
]
}
]);
// 只显示用户权限级别允许的内容
db.secureDocs.aggregate([
{
$redact: {
$cond: {
if: { $gt: [{ $ifNull: ['$accessLevel', 'public'] }, { $literal: 'public' }] },
then: {
$cond: {
if: { $eq: ['$$ROOT._currentUserRole', 'admin'] },
then: '$$descend',
else: '$$prune'
}
},
else: '$$descend'
}
}
}
]);
输出：1) $facet 一次查询返回用户概览统计、活跃度分布分桶、消费层级分布三个并行结果；2) $redact 根据角色裁剪文档，admin 看到完整字段，普通用户看不到内部成本和利润信息；3) 嵌套字段标记模式实现字段级权限控制。
$facet 与 $redact 的使用建议：1. $facet 的每个子管道共享同一输入文档集，但互不影响——一个子管道的错误不会中断其他子管道；2. $facet 总输入大小不能超过 100MB（内存限制），大数据集需先 $match/$project 缩减；3. $redact 比 $project 更灵活但更难调试——优先用 $project 显式排除字段，$redact 适用于嵌套层级不确定的场景；4. $redact 的三个动作——$$descend（继续深入嵌套）、$$prune（丢弃当前文档/字段）、$$keep（保留当前文档/字段，不再深入）。
❓ 常见问题
常见问题的设计意图：这些问题不只是 FAQ，更是设计决策的延伸思考——$cond vs $switch 涉及可读性与性能的权衡，时区涉及存储策略的选择，类型转换涉及弱类型系统的风险防控。理解"为什么"比记住"是什么"更重要。
timezone 参数（IANA 时区名，如 'Asia/Tokyo'）。$convert 指定 onError 处理。📖 小节
- 条件表达式：$cond（if-else）、$switch（多分支）、$ifNull（空值处理）
- 日期操作：$year/$month/$dayOfWeek + $dateToString
- 类型转换：$toString/$toInt/$toDecimal/$toDate
- 字符串操作：$concat/$substr/$toUpper
- 数组操作：$arrayElemAt/$size/$map/$filter
知识点串联：聚合管道进阶的 5 个主题构成了数据处理的能力栈——条件表达式是"逻辑层"（根据数据做决策），日期/类型/字符串/数组操作是"变换层"（将数据转换为所需格式）。在实际管道中，这些操作交织使用：$group 计算统计量 → $addFields 用 $switch 条件分层 → $project 用 $dateToString 格式化日期 → 输出。掌握变换层是通向聚合管道精通的必经之路。
聚合管道的性能优化全景：聚合管道的性能取决于三个维度——1. I/O 量（扫描多少文档/读取多少索引条目）：$match 前置 + hint() 选索引可以优化；2. 内存占用（管道中间结果占多少内存）：$project 精简字段 + allowDiskUse 溢出到磁盘可以优化；3. CPU 计算（$group/$sort 的计算复杂度）：减少 _id 复杂度 + 利用索引排序可以优化。每个维度都有对应的设计原则和调优手段，系统化理解比逐个记忆优化技巧更有效。
从聚合管道到 ETL：聚合管道本质上是一个轻量级 ETL（Extract-Transform-Load）工具——$match 是 Extract（从集合抽取数据），$project/$addFields/$convert 是 Transform（数据清洗和变换），$out/$merge 是 Load（写入目标集合）。对于简单的数据管道（单源→变换→目标），聚合管道比 Spark/Airflow 更轻量更快速。但当 ETL 需要跨数据源（MongoDB + MySQL + S3）或复杂调度（依赖链、重试、告警）时，应使用专业 ETL 工具而非聚合管道。
📝 作业
作业能力层级：5 道作业对应 3 个能力层级——基础题（⭐）测试单操作符使用能力，进阶题（⭐⭐）测试组合运用能力，挑战题（⭐⭐⭐）测试独立设计能力。建议按顺序完成，每道题先用中文描述管道的每一步应该做什么（伪管道），再翻译为代码。
- 基础题（⭐）：用 $switch 给订单状态添加中文标签。
- 基础题（⭐）：用 $dateToString 格式化订单日期。
- 进阶题（⭐⭐）：用户分层（$switch 区分 VIP/Gold/Silver）。
- 进阶题（⭐⭐）：用 $map 给所有标签转大写。
- 挑战题（⭐⭐⭐）：月度销售报表 + 同比增长率（$setWindowFields + $shift）。
挑战题指导：月度销售报表 + 同比增长率是最接近真实业务的挑战题。实现步骤：1. $match 过滤已支付订单；2. $group 按 {year, month} 分组计算 revenue/orderCount/avgOrderValue；3. $sort 按年月排序；4. $setWindowFields + $shift 获取上月收入；5. $addFields 计算环比增长率。注意 $shift 的 by: -1 表示"前一行"（上月），by: 1 表示"后一行"（下月）。
