$isoWeek（ISO 周数）
最后更新：2026-10-09
$isoWeek（ISO 周数）
$isoWeek 按 ISO 8601 标准返回日期所在周是全年第几周（1 到 53）。ISO 周从周一开始，第一个包含周四的周为第 1 周，与美式规则的 $week（周日开始、可能返回 0）不同。常用于国际化业务的周统计，常与 $isoWeekYear 搭配组成「年-周」标识。timezone 决定周的边界。
| 分类 | 日期 |
|---|---|
| MongoDB 版本 | 1.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $isoWeek: { date: <日期表达式>, timezone: <时区> } }⚙️ 参数
| date | 必填，日期表达式。 |
|---|---|
| timezone | 可选，计算依据的时区，缺省 UTC。 |
返回值：ISO 周数（1-53）整数；date 为 null 时返回 null。
▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $isoWeek：按 ISO 周聚合销售额
db.sales.aggregate([
{ $group: {
_id: { $isoWeek: { date: '$soldAt', timezone: 'Asia/Shanghai' } },
total: { $sum: '$amount' }
} }
])运行结果：
{ "_id": 39, "total": 9800 }
{ "_id": 40, "total": 10450 }📌 注意事项
- ISO 周从周一开始，第 1 周是含当年第一个周四的周
- 与 $week 不同：$isoWeek 不会返回 0，取值范围 1 到 53
- 常与 $isoWeekYear、$isoDayOfWeek 组合成完整周标识
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q返回范围是多少？
A1 到 53，不会出现 0。
Q和 $week 有什么区别？
A$week 从周日开始、可能返回 0；$isoWeek 遵循 ISO 8601，从周一开始。
Q跨年的周怎么归属？
A按 ISO 规则归到含周四的那一年，配合 $isoWeekYear 取正确的年份。
