$dateDiff（日期差值）
最后更新：2026-10-09
$dateDiff（日期差值）
$dateDiff 计算两个日期在指定单位下的差值，返回整数，是计算年龄、订阅时长、订单停留时间等场景的常用操作符。unit 支持 year、month、week、day、hour、minute、second、millisecond；结果按完整单位边界取整，例如按 year 计算时只有跨过完整年份才会加 1。startOfWeek 可指定一周起始日，仅当 unit 为 week 时生效。timezone 影响差值计算所依据的日历，跨时区场景务必指定。
| 分类 | 日期 |
|---|---|
| MongoDB 版本 | 5.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $dateDiff: { startDate: <起始日期>, endDate: <结束日期>, unit: <时间单位>, timezone: <时区>, startOfWeek: <周起始日> } }⚙️ 参数
| startDate / endDate | 必填，差值的起止日期。 |
|---|---|
| unit | 必填，差值单位，同上 8 种。 |
| timezone | 可选，计算依据的时区。 |
| startOfWeek | 可选，仅 unit 为 week 时生效，取值如 Monday、Sunday。 |
返回值：endDate 减 startDate 的整数差值；任一日期为 null 时返回 null。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $dateDiff：按年计算用户年龄
db.users.aggregate([
{ $project: {
ageYears: { $dateDiff: { startDate: '$birthDate', endDate: '$$NOW', unit: 'year' } }
} }
])运行结果：
{ "_id": 1, "ageYears": 28 }
{ "_id": 2, "ageYears": 31 }📌 注意事项
- 结果为 endDate 减 startDate，可为负数
- 按较大单位计算时按完整边界截断：year 只数完整年份，不做四舍五入
- startOfWeek 只对 week 单位生效，取值为 Monday 到 Sunday
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q结果有小数吗？
A没有，$dateDiff 返回整数，按单位边界截断。
Q能返回负数差值吗？
A能，endDate 早于 startDate 时返回负数。
Q怎么算两个日期差几天？
Aunit 设为 day 即可，注意时区会导致日历日边界不同。
