在MongoDB聚合管道的官方文档里翻遍所有阶段和运算符，确实找不到一个叫$timeRange的东西。这个名称更多出现在一些内部框架、ORM封装或者技术分享中，用来表示根据时间字段对集合做范围划分。时间范围本身并不复杂，真正容易出错的是对MongoDB日期存储机制、时区处理以及聚合阶段组合方式的理解。如果直接用错误的字段类型或错误的比较方式，很可能会查出空结果或者漏掉边界数据。
MongoDB中的日期字段在底层存储为UTC时间的64位整数，也就是从1970年1月1日以来的毫秒数。聚合管道里看到的ISODate("2025-01-01T00:00:00Z")只是驱动或shell层的表示，实际比较时仍然是数值比较。因此时间范围过滤的关键不是去寻找一个叫$timeRange的阶段，而是正确使用$match、$expr以及日期运算符。
一、先厘清概念：$timeRange并不存在于官方聚合管道
MongoDB聚合管道由多个阶段组成，常见的有$match、$group、$sort、$project、$bucket、$dateTrunc等。官方从未发布过名为$timeRange的聚合阶段或表达式。如果某个文档中提到$timeRange，大概率是应用层自己定义的一个辅助函数，用来生成时间过滤条件，或者是某个ORM框架提供的查询封装。理解这一点可以避免在官方文档中做无意义的搜索，也能把注意力放到正确的时间处理方式上。
时间范围问题的本质可以拆成三部分：第一，如何用$match圈定起止时间；第二，如何把时间字段转换成合适的粒度进行分组；第三，如何处理时区、动态时间范围以及索引效率。这三个问题解决之后，$timeRange这个名称反而可以留给业务封装使用，让管道代码更易读。
二、用$match和日期边界完成时间范围过滤
最简单的范围过滤使用$gte和$lt组合，形成左闭右开区间。这样做的好处是边界清晰，不会重复计算。例如要统计2025年1月的订单，应该使用createdAt大于等于1月1日零点，并且小于2月1日零点，而不是小于等于1月31日23点59分，因为毫秒级的末端边界很容易漏掉数据。
db.orders.aggregate([
{
$match: {
createdAt: {
$gte: ISODate("2025-01-01T00:00:00Z"),
$lt: ISODate("2025-02-01T00:00:00Z")
}
}
},
{
$count: "totalOrders"
}
])
如果时间字段存储的是字符串而不是Date类型，上述比较会按字符串字典序进行，结果可能不符合预期。例如字符串"2025-01-10"会小于"2025-01-09"吗？不会，因为字典序中"1"比"9"小，但整体比较时逐位进行，"2025-01-10"和"2025-01-09"前八位相同，第九位是"1"和"0"，所以"2025-01-10"反而小于"2025-01-09"。为了避免这种坑，应该使用$toDate在管道中做类型转换，或者从源头上就把字段存成Date类型。
动态时间范围则可以使用$$NOW变量和$dateSubtract配合。比如查询最近7天的数据，不需要在应用层计算具体日期，直接让管道自己计算边界。
db.events.aggregate([
{
$match: {
$expr: {
$gte: [
"$createdAt",
{
$dateSubtract: {
startDate: "$$NOW",
unit: "day",
amount: 7
}
}
]
}
}
}
])
这里用$expr允许在$match中使用聚合表达式，比较字段与计算出的日期。需要注意$$NOW在管道执行时会被求值一次，而不是每条文档都变化，因此适合作为固定边界。对于索引来说，$expr通常无法利用普通索引，如果数据量很大，建议在应用层先计算好边界日期，再交给$match做普通比较。
三、按固定时间窗口聚合：$dateTrunc与$bucket配合
时间范围过滤解决的是哪些文档参与计算，而聚合统计往往需要按小时、天、周等时间窗口分组。$dateTrunc可以把日期截断到指定单位，例如截断到天，这样同一天内的所有时间都变成当天零点，之后交给$group统计即可。
db.orders.aggregate([
{
$group: {
_id: {
$dateTrunc: {
date: "$createdAt",
unit: "day",
binSize: 1
}
},
orderCount: { $sum: 1 }
}
},
{
$sort: { _id: 1 }
}
])
如果时间窗口不是固定大小，比如要按早中晚三个班次统计，可以使用$bucket自定义边界。$bucket会根据boundaries数组把文档分配到不同的桶中，默认包含左边界不包含右边界。下面示例将一天划分为0到8点、8到16点、16到24点三个班次。
db.shifts.aggregate([
{
$bucket: {
groupBy: {
$hour: { date: "$createdAt", timezone: "Asia/Shanghai" }
},
boundaries: [0, 8, 16, 24],
default: "其他",
output: {
count: { $sum: 1 }
}
}
}
])
使用$hour时通过timezone参数指定时区非常重要，因为MongoDB默认使用UTC。如果业务位于东八区，不指定时区会导致凌晨0点到8点的班次被错误归到前一天。类似地，$dateToString也支持timezone参数，可以在格式化日期时直接转换到目标时区，避免应用层二次处理。
四、封装一个$timeRange语义：让管道更清晰
既然MongoDB没有内置$timeRange，我们完全可以在应用层封装一个函数来生成标准的时间过滤阶段。这样业务代码中出现的$timeRange就是一个团队内部约定的函数名，而不是官方语法。下面是一个基于Node.js的简单封装，返回一个$match阶段。
function timeRangeMatch(field, start, end) {
const match = {};
match[field] = {};
if (start) {
match[field].$gte = new Date(start);
}
if (end) {
match[field].$lt = new Date(end);
}
return { $match: match };
}
const pipeline = [
timeRangeMatch("createdAt", "2025-01-01T00:00:00Z", "2025-02-01T00:00:00Z"),
{ $count: "total" }
];
db.orders.aggregate(pipeline);
这种封装的好处是边界逻辑集中管理，可以在函数内部统一处理时区转换、参数校验以及默认值。例如当end为空时，可以自动使用当前时间；当start为空时，不设置$gte。另外还可以扩展支持startInclusive和endInclusive参数，根据业务需要选择使用$gte还是$gt。
需要注意的是，MongoDB聚合管道中虽然可以使用$function定义自定义JavaScript函数，但会带来性能损耗和可移植性问题，不推荐用来实现时间范围判断。更好的做法是把时间边界逻辑放在应用层生成管道，保证数据库端只做高效的比较和聚合。理解了这一点，无论项目里有没有$timeRange这个封装，你都能快速定位问题并写出正确的管道。
MongoDB聚合管道$timeRange时间范围聚合修改时间：2026-09-17 06:13:30