$isoWeekYear（ISO 周年）
最后更新：2026-10-09
$isoWeekYear（ISO 周年）
$isoWeekYear 返回日期所在 ISO 周对应的年份，与 $isoWeek 配套使用。由于 ISO 周可能跨年（如 12 月 31 日可能属于下一年的第 1 周），周所属年份可能与日历年不同，此时只有用 $isoWeekYear 才能得到正确的年份归属。典型场景是构造「年-周」维度的分组键。timezone 决定周的边界。
| 分类 | 日期 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $isoWeekYear: { date: <日期表达式>, timezone: <时区> } }⚙️ 参数
| date | 必填，日期表达式。 |
|---|---|
| timezone | 可选，计算依据的时区，缺省 UTC。 |
返回值：ISO 周年份整数；date 为 null 时返回 null。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $isoWeekYear + $isoWeek：年-周分组
db.sales.aggregate([
{ $group: {
_id: { y: { $isoWeekYear: { date: '$soldAt' } }, w: { $isoWeek: { date: '$soldAt' } } },
total: { $sum: '$amount' }
} }
])运行结果：
{ "_id": { "y": 2026, "w": 39 }, "total": 9800 }
{ "_id": { "y": 2026, "w": 40 }, "total": 10450 }📌 注意事项
- 年末年初的日期，ISO 周年可能与日历年相差 1
- 与 $isoWeek 一起使用，单用意义不大
- timezone 缺省为 UTC，统计前先统一时区
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q和 $year 有什么区别？
A$year 返回日历年，$isoWeekYear 返回 ISO 周所属年份，跨年周两者可能不同。
Q什么时候需要它？
A按「年-周」分组时，用 $isoWeekYear 拼 $isoWeek 作为分组键。
Q单独用有意义吗？
A意义不大，它只有与 $isoWeek 搭配才能表达周归属。
