本文详解如何利用 MongoDB 5.0+ 的 $setWindowFields 聚合阶段，在 Mongoose 中为按日期排序的文档流添加实时累计和（cumulative sum）字段，适用于时间序列图表数据准备。
本文详解如何利用 mongodb 5.0+ 的 `$setwindowfields` 聚合阶段，在 mongoose 中为按日期排序的文档流添加实时累计和（cumulative sum）字段，适用于时间序列图表数据准备。
在构建时间序列可视化（如折线图）时，常需为每条记录附加“截至当前的累计值”——即按时间顺序排列后，从第一条到当前条的 value 字段累加和。该需求无法通过简单 $group 实现，因其要求保留原始文档结构并逐行计算前缀和。MongoDB 5.0 引入的窗口函数（Window Functions）正是为此类场景而生，其中 $setWindowFields 是最直接、高效且声明式的解决方案。
✅ 核心实现：使用 $setWindowFields 计算分组内累计和
以下聚合管道可在 Mongoose 中直接调用（假设模型名为 Entry）：
const result = await Entry.aggregate([
{
$setWindowFields: {
partitionBy: "$type", // 按 type 分组独立计算（如需全局累计，可省略此行）
sortBy: { date: 1 }, // 按 date 升序排序（确保时间先后顺序）
output: {
sum: {
$sum: "$value",
window: { documents: ["unbounded", "current"] } // 累计从首条到当前条
}
}
}
},
{
$sort: { date: 1 } // 最终按 date 排序输出（与图表时间轴一致）
}
]).exec();
? 注意：date 字段必须为 ISODate 格式（如 new Date('2000-01-01')），而非字符串 '01-01-2000'。若原始数据为字符串，请先在插入或预处理阶段统一转换，否则排序将失效（字符串排序 ≠ 时间排序）。
? 关键要点说明
- partitionBy 是可选但推荐的：当需按类别（如 type）分别累计时启用；若只需全局时间序列累计（所有文档统一累加），删除该字段即可。
- window: ["unbounded", "current"] 表示“从分区开头到当前文档”，等价于 SUM(value) OVER (PARTITION BY type ORDER BY date ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)。
- 性能友好：整个操作在数据库端完成，无需应用层循环或多次查询，避免 N+1 问题。
- 兼容性要求：MongoDB ≥ 5.0，且部署需启用「featureCompatibilityVersion: "5.0"」；Mongoose ≥ 6.0（支持现代聚合语法）。
⚠️ 常见陷阱与规避建议
-
❌ 错误：date 为字符串格式 → 导致 $sort 和 sortBy 失效（如 '01-03-2000' ✅ 正确做法：存储时使用 Date 类型，或在聚合中先 $convert：
{ $addFields: { dateISO: { $dateFromString: { dateString: "$date" } } } }, { $setWindowFields: { sortBy: { dateISO: 1 }, ... } } ❌ 错误：未对 date 字段建立索引 → 大数据量下聚合性能下降。
✅ 建议：创建复合索引 {"type": 1, "date": 1}（若使用 partitionBy）或 {"date": 1}（全局累计）。
✅ 最终输出效果（匹配示例）
输入经上述聚合后，将严格按 date 升序输出，并为每条文档注入 sum 字段，其值为同 type 分区内、时间 ≤ 当前文档的所有 value 之和——完全满足折线图所需的逐点累计数据结构。
该方案简洁、健壮、可扩展，是 Mongoose 时间序列累加计算的现代标准实践。
