在处理时间序列数据时，经常需要把日期拆开来看，比如统计每个月的订单量、分析每天各时段的访问情况。MongoDB聚合管道提供了$dateToParts操作符，可以把一个完整的日期值分解成年、月、日、时、分、秒等独立字段，拆出来的字段可以直接参与分组、筛选和计算。这篇文章详细介绍$dateToParts的语法结构、参数细节和几个典型的实战用法。
$dateToParts的基本语法与输出字段
$dateToParts的语法结构非常简单，它接收一个文档形式的参数，包含三个可选字段：date指定要分解的日期表达式，timezone指定时区，iso8601决定是否按照ISO 8601标准输出。先看一个最基本的例子：
db.orders.aggregate([
{
$project: {
orderDateParts: {
$dateToParts: { date: "$createdAt" }
}
}
}
])假设createdAt的值是2024-03-15T08:30:45.500Z，那么上面的输出结果会是这样一个文档：{ "year" : 2024, "month" : 3, "day" : 15, "hour" : 8, "minute" : 30, "second" : 45, "millisecond" : 500 }。可以看到，一次操作就把日期拆成了七个独立字段，每个字段都是数值类型，可以直接用于后续的数学运算或分组统计。
需要注意的一点是，如果date表达式的值是null或者缺失，$dateToParts会返回null；如果传入的不是合法的日期类型，则会直接报错。所以在数据质量不稳定的集合上使用时，建议先用$match过滤掉无效记录，或者在date参数里用$ifNull做一个兜底处理，避免整个管道因为脏数据而中断。
timezone参数与iso8601参数的使用细节
默认情况下，$dateToParts按照UTC时区进行分解，而实际业务中我们往往需要按北京时间来拆分。这时就要用到timezone参数，它可以接受奥尔森时区标识符（比如Asia/Shanghai）或者UTC偏移量（比如+08:00）两种写法：
db.orders.aggregate([
{
$project: {
// 按北京时间拆分日期
localParts: {
$dateToParts: {
date: "$createdAt",
timezone: "Asia/Shanghai"
}
},
// 使用偏移量的写法，效果相同
offsetParts: {
$dateToParts: {
date: "$createdAt",
timezone: "+08:00"
}
}
}
}
])时区处理是一个非常容易踩坑的地方。举个例子，一条订单的UTC时间是2024-03-15T18:30:00Z，如果不加时区参数直接分解，得到的day是15；但加上Asia/Shanghai后，因为本地时间已经是3月16日凌晨2点半，day会变成16，month、hour等字段也会相应变化。做按天统计时如果不注意这一点，就会出现数据对不上的情况。
另一个参数iso8608控制输出格式。当设置为true时，输出字段会变成isoWeekYear、isoWeek、isoDayOfWeek和hour、minute等，采用ISO 8601标准的周年表示法。isoDayOfWeek的范围是1到7，周一为1，周日为7。这种格式在做一些跨年的周统计报表时特别有用，因为它能正确处理年末年初那一周的归属问题，比传统的month字段更可靠。
实战场景：按年月分组统计与按小时分析
$dateToParts最常见的用法是配合$group做时间维度的聚合。比如要统计每个月的订单数量和总金额，可以先在$project阶段把日期拆开，再用$group按年月两个字段分组：
db.orders.aggregate([
{
$match: {
createdAt: { $gte: ISODate("2024-01-01") }
}
},
{
$project: {
year: { $year: "$createdAt" },
month: { $month: "$createdAt" },
amount: 1
}
},
{
$group: {
_id: { year: "$year", month: "$month" },
orderCount: { $sum: 1 },
totalAmount: { $sum: "$amount" }
}
},
{
$sort: { "_id.year": 1, "_id.month": 1 }
}
])上面这个例子里还展示了另一种思路：如果只需要单独取某个部件，可以直接用$year、$month、$dayOfMonth这些更轻量的操作符，不必把整个日期都拆开。但如果要同时用到多个部件，一次$dateToParts会比多次调用单独操作符更简洁，管道结构也更清晰。
再看一个按小时分析的例子，比如统计某个活动页面各时段的访问量分布。可以用$dateToParts把时间拆出来，然后只保留hour字段参与分组，同时结合时区参数保证统计口径是北京时间：
db.pageViews.aggregate([
{
$project: {
hour: {
$dateToParts: {
date: "$viewTime",
timezone: "Asia/Shanghai"
}
}
}
},
{
$group: {
_id: "$hour.hour",
viewCount: { $sum: 1 }
}
},
{ $sort: { _id: 1 } }
])这种方式的好处是拆解和分组逻辑全部在数据库端完成，不需要把数据拉到应用层再用代码逐条处理，对于数据量较大的集合来说，性能优势非常明显。另外，拆出来的字段还可以和$facet结合，在一条聚合语句里同时输出按天、按小时等多个维度的统计结果。
常见问题与使用建议
第一个常见问题是字段类型校验。$dateToParts要求date参数必须是能解析为日期的表达式，包括Date类型、时间戳以及ISODate字符串。如果集合里日期存的是普通字符串，需要先用$dateFromString转换，否则聚合会报错。
第二个建议是合理利用索引。虽然$dateToParts本身在$project阶段执行，无法直接利用索引，但如果在它前面加上针对日期范围的$match条件，MongoDB就能走索引先过滤数据，再做拆解和分组，整体性能会好很多。这也是聚合管道优化的基本原则之一：能提前过滤的尽量提前。
最后一点，如果MongoDB版本在3.6以下，是不支持$dateToParts的，需要先确认版本。对于新项目，建议同时了解$dateTrunc操作符，它可以从MongoDB 5.0开始提供按时间单位截断的能力，与$dateToParts配合使用可以让时间维度的聚合语句写起来更加得心应手。掌握好这两个操作符，日期相关的统计分析基本都能在数据库层面优雅地解决。
MongoDB$dateToParts聚合管道修改时间：2026-09-05 20:54:43