$dateToString（日期格式化）
最后更新：2026-10-09
$dateToString（日期格式化）
$dateToString 按指定格式字符串将日期转换为字符串，是聚合管道格式化输出日期的最常用方式。格式串使用占位符（如 %Y 年、%m 月、%d 日、%H 时），与 strftime 风格类似。date 为 null 或缺失时，可返回 null 或指定 onNull 默认值。
| 分类 | 日期 |
|---|---|
| MongoDB 版本 | 3.0+ |
| 示例语言 | mongosh (Shell) |
📝 语法
{ $dateToString: { format: <格式串>, date: <日期表达式>, timezone: <时区>, onNull: <默认值> } }▶ 示例
请在本地安装的 mongosh 中执行以下命令（需已启动 mongod）：
// $dateToString：格式化订单日期
db.orders.aggregate([
{ $project: {
dateStr: { $dateToString: { format: "%Y-%m-%d", date: "$createdAt" } }
} }
])运行结果：
{ "_id": 1, "dateStr": "2026-09-25" }
{ "_id": 2, "dateStr": "2026-09-24" }📌 注意事项
- 占位符：%Y 四位年、%m 两位月、%d 两位日、%H 两位时、%M 分、%S 秒
- timezone 可选，缺省用 UTC；可用 "+08:00" 或 "Asia/Shanghai" 等 IANA 时区
- date 为 null 时：onNull 有值则返回之，否则返回 null
- MongoDB 6.3+ 新增 $dateToString 的 format 简写模式
🏷️ 相关标签
💡 相关案例
更多实战案例即将上线，敬请期待。
📚 相关教程
❓ 常见问题
Q时区怎么写？
A用 IANA 时区名（如 "Asia/Shanghai"）或 UTC 偏移（如 "+08:00"）。缺省为 UTC。
Q$dateToString 支持哪些格式说明符？
A常用有 %Y（年）、%m（月）、%d（日）、%H（时）、%M（分）、%S（秒）、%L（毫秒）、%z（时区偏移）、%j（年内第几天）。完整清单见官方文档。
Qdate 字段不是日期类型会怎样？
A$dateToString 要求输入是 Date 类型，否则返回 null 或报错（取决于是否开启严格模式）。可先用 $toDate 转换。
Q可以输出 ISO 8601 格式吗？
A可以。用 %Y-%m-%dT%H:%M:%S.%LZ 组合即可输出类似 2026-10-01T08:30:00.000Z 的字符串；或直接用 $isoDate 表达式。
