$dateSubtract（日期减法）
最后更新：2026-10-09
$dateSubtract（日期减法）
$dateSubtract 从指定日期减去一定数量的时间单位，返回新日期，是 $dateAdd 的镜像操作。常用于计算会员过期日、优惠券有效期起点或数据保留期限。unit 支持 year、month、week、day、hour、minute、second、millisecond；amount 为负数时等价于加法。timezone 可选，指定计算所依据的时区日历。与 $dateAdd 一样，可在 $project、$set 等聚合阶段使用，date 为 null 或缺失时返回 null。
| 分类 | 日期 |
|---|---|
| MongoDB 版本 | 5.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $dateSubtract: { startDate: <日期表达式>, unit: <时间单位>, amount: <数值>, timezone: <时区> } }⚙️ 参数
| startDate | 要被减的日期，可为 Date、时间戳或日期表达式。 |
|---|---|
| unit | 时间单位：year、month、week、day、hour、minute、second、millisecond。 |
| amount | 减去的数量，正数减、负数加；超出 int64 范围会报错。 |
| timezone | 可选，计算基于的时区。 |
返回值：减去后的新日期（BSON Date）；startDate 为 null 或缺失时返回 null。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $dateSubtract：到期日前 3 天发提醒（按东八区）
db.orders.aggregate([
{ $project: {
remindAt: { $dateSubtract: { startDate: '$dueDate', unit: 'day', amount: 3, timezone: '+08:00' } }
} }
])运行结果：
{ "_id": 1, "remindAt": ISODate("2026-10-22T00:00:00Z") }
{ "_id": 2, "remindAt": ISODate("2026-11-12T00:00:00Z") }📌 注意事项
- 与 $dateAdd 参数完全一致，只是方向相反
- 月份减法同样按结果月的天数截断
- 结果可以早于 1970 年，BSON Date 支持负时间戳
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q$dateSubtract 和 $dateAdd 什么关系？
A参数一致、方向相反；amount 为负数时二者等价。
Q能减出 1970 年之前的日期吗？
A可以，BSON Date 支持 1970 年之前的负时间戳。
Q和 $dateDiff 有什么区别？
A$dateSubtract 返回新日期，$dateDiff 返回两个日期之间的差值整数。
