MongoDB使用$hour和$dayOfWeek提取日期的小时和星期几

MongoDB 日期提取，一篇讲透 $hour 和 $dayOfWeek 的坑与巧用

在 MongoDB 中提取日期字段的小时或星期几是一个常见需求，例如按小时统计订单量或过滤周末日志数据。看似简单的操作，在实际编写聚合管道时却容易踩坑。本文将快速拆解几个容易出错的关键点，并给出每个场景下的正确处理方式。

提取日期字段的小时值：用 $hour 处理 ISODate 或时间戳

使用 $hour 提取小时前，必须明确其前置条件：它只接受 Date 类型（即 ISODate 格式），如果输入的是字符串或纯数字时间戳，会直接返回 null，且不会报错。这一特点在线上聚合任务中非常隐蔽，常常排查半天才发现是字段类型不匹配。

• 检查类型：可通过 {$type: "$field"} 查看字段类型，返回 "date" 才能安全使用。
• 字符串转日期：若字段格式为 "2024-05-20T14:30:00Z"，可先使用 $dateFromString 转换为日期对象。
• 毫秒时间戳：MongoDB 4.0 及以上版本可直接用 {$toDate: "$ts_field"} 转换，也可用 $dateFromParts 方式处理。
• 时区问题：$hour 默认按 UTC 解析时间，若需要本地时区的小时值，通常配合 $dateToString 的 timezone 参数进行预处理。

{$project: {hour_of_event: {$hour: "$created_at"}}}

提取星期几：$dayOfWeek 返回 1（周日）到 7（周六）

$dayOfWeek 的返回逻辑是 周日 = 1，这与 JavaScript 的 getDay() 一致，但与 ISO 8601 标准（周一 = 1）冲突。如果业务需求是“周一显示为1”，不能直接使用 $dayOfWeek 的返回值，需手动偏移。

• 直接使用：{$dayOfWeek: "$order_time"} → 周日=1，周六=7。适用于统计非工作日或按周几分组。
• 转 ISO 标准（周一=1）：可先执行 {$add: [{$dayOfWeek: "$order_time"}, -1]}，然后对“周日变 0”的情况做特殊处理。更严谨的做法是用 $cond：{$cond: [{$eq: [{$dayOfWeek: "$order_time"}, 1]}, 7, {$subtract: [{$dayOfWeek: "$order_time"}, 1]}]}
• 空值容错：如果字段可能为 null 或无效日期，$dayOfWeek 也会返回 null。建议在前置阶段使用 $ifNull 或 $cond 兜底。

聚合中同时提取多个时间单位：避免重复解析日期

一次 $dateFromString 或 $toDate 的解析开销在百万级数据量下不可忽视。如果需要同时提取小时、星期几、月份等信息，最忌讳的做法是每次获取一个单位就重复调用转换操作符。正确做法是：解析一次，复用多次。

• 错误示范：在 $project 阶段连续写入三遍 {$toDate: "$ts"}
• 推荐方式：先在 $addFields 阶段将解析好的日期存为临时字段（如 parsed_date），后续所有 $hour、$dayOfWeek 调用都基于该临时字段。
• 注意内存：临时字段虽方便，但在极大数据量的聚合中会增加文档体积，需平衡可读性与资源消耗。

聚合阶段顺序影响结果：$project 中不能依赖未定义字段

$hour 和 $dayOfWeek 属于表达式操作符，只能在允许表达式的阶段（如 $project、$addFields、$group 的 $sum 表达式内部）使用。它们不能直接出现在 $match 阶段作为查询条件，除非配合 $expr 包装。

• 按星期几筛选：若需筛选“星期几 = 2”，必须写成：{$match: {$expr: {$eq: [{$dayOfWeek: "$dt"}, 2]}}}
• 按小时分桶：在 $group 中直接写 {$group: {_id: {$hour: "$ts"}, count: {$sum: 1}}} 是受支持的用法。
• 调试不易：嵌套表达式中若某个环节格式错误（例如 {$hour: {$toDate: "$str_ts"}} 中 $str_ts 转换失败），整个字段会返回 null，但 MongoDB 不会抛出异常。线上排查时通常需要先将中间字段输出查看，再定位问题。

最后补充一点：时区的隐含行为以及字符串日期的静默失败，是导致线上聚合任务统计偏差的主要来源。处理前先确认字段类型，处理后用小样本进行验证，可大幅节省排查时间。