The $dateToString operator formats a BSON Date into a text string inside MongoDB aggregation pipelines. Use it for report labels, API responses, CSV exports, or any output where dates must appear in a specific human-readable layout.
Date → string.
date, format.
%Y, %m, %d, etc.
Local display time.
Reports, exports.
Format vs parse.
In MongoDB’s aggregation framework, the $dateToString operator takes a BSON Date and a format pattern and returns a string. For example, formatting ISODate("2024-06-15T14:30:00Z") with format: "%Y-%m-%d" produces "2024-06-15".
$dateToString returns a string, not a Date. Both date and format are required. Use timezone when the formatted string should reflect local time rather than UTC.
The $dateToString operator takes an object with a required date and format:
{
$dateToString: {
date: <dateExpression>,
format: <stringExpression>,
timezone: <stringExpression>,
onNull: <stringExpression>
}
}date — required; the BSON date to format (field, $$NOW, or literal).format — required; pattern with format specifiers (e.g. "%Y-%m-%d").timezone — optional Olson timezone ID for local-time formatting.onNull — optional string returned when date is null or missing.%Y — four-digit year (2024)%m — month 01–12%d — day 01–31%H — hour 00–23 (24-hour clock)%M — minute 00–59%S — second 00–60%L — millisecond 000–999%Z — timezone offset (e.g. +0530)| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | date, format |
| Return type | String |
| Format pattern | Uses %Y, %m, %d, etc. |
| MongoDB version | 3.6+ |
{
$dateToString: {
format: "%Y-%m-%d",
date: "$createdAt"
}
}2024-06-15 style
{
$dateToString: {
format: "%Y-%m-%d %H:%M",
date: "$loggedAt"
}
}Include hours and minutes
{
$dateToString: {
format: "%m/%d/%Y",
date: "$orderDate"
}
}06/15/2024 style
{
$dateToString: {
format: "%Y-%m-%d %H:%M %Z",
date: "$eventAt",
timezone: "America/New_York"
}
}Local time display
Format order dates for reports, build readable timestamps, show local timezone labels, and handle null dates with $dateToString.
Use an orders collection and produce a standard date string from orderDate.
Suppose you have an orders collection with BSON date fields:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"item": "Laptop",
"orderDate": ISODate("2024-06-15T14:30:00Z")
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"item": "Mouse",
"orderDate": ISODate("2024-03-22T09:15:00Z")
}
]Format orderDate as YYYY-MM-DD for CSV export or dashboards:
db.orders.aggregate([
{
$project: {
item: 1,
orderDate: 1,
orderDateStr: {
$dateToString: {
format: "%Y-%m-%d",
date: "$orderDate"
}
}
}
}
])%Y = four-digit year, %m = zero-padded month, %d = zero-padded day.timezone.orderDate BSON field remains available for sorting and filtering.Readable labels, local timezone display, and null-safe formatting.
Build a full timestamp string for email receipts or log summaries:
db.orders.aggregate([
{
$project: {
item: 1,
receiptLabel: {
$dateToString: {
format: "%Y-%m-%d at %H:%M UTC",
date: "$orderDate"
}
}
}
}
])
// orderDate: 2024-06-15T14:30:00Z → "2024-06-15 at 14:30 UTC"Literal text in the format string (like " at ") is copied as-is. Combine %Y, %m, %d, and time specifiers to build any fixed-layout timestamp string.
Show event times as they appear in Eastern Time for US users:
db.events.aggregate([
{
$project: {
title: 1,
eventAt: 1,
localDisplay: {
$dateToString: {
format: "%Y-%m-%d %H:%M %Z",
date: "$eventAt",
timezone: "America/New_York"
}
}
}
}
])The timezone field shifts how the date is interpreted before formatting. %Z appends the offset. Essential when the same UTC instant should read differently per region.
Return a placeholder when optional date fields are null:
db.users.aggregate([
{
$project: {
name: 1,
lastLoginDisplay: {
$dateToString: {
format: "%Y-%m-%d",
date: "$lastLogin",
onNull: "Never logged in"
}
}
}
}
])
// lastLogin: null → "Never logged in"
// lastLogin: ISODate(...) → formatted date stringonNull avoids pipeline errors and gives user-friendly output when dates are optional. Keep the raw lastLogin field for logic; use the formatted string only for display.
$group (prefer BSON dates for performance when possible).$dateToString Worksdate is evaluated per document — a field, $$NOW, or literal ISODate.
MongoDB maps the date through format specifiers, optionally using timezone.
If date is null, onNull provides a fallback; otherwise the formatted text is output.
Use in exports, UI labels, or alongside $dateFromString for round-trip string conversion.
The $dateToString operator is the standard way to turn BSON dates into formatted text in MongoDB aggregation pipelines. With flexible format specifiers and optional timezone support, it replaces manual string concatenation for display output.
Pair it with $dateFromString when you need to parse strings back into dates, and keep BSON Date fields in your schema for indexing and range queries. Use formatted strings only where human readability matters.
timezone when users expect local calendar datesformat to your export or API contractonNull for optional date fields in reports$dateToString with $dateFromString$dateToParts suffice%m and %d$dateToStringUse these points when formatting dates as strings in MongoDB.
Date → string.
Purposedate, format.
SyntaxNot a Date type.
OutputLocal display time.
OptionFormat vs parse.
ImportantMove on to $dateTrunc to truncate dates to period boundaries, or review $dateFromString for the reverse conversion.
5 people found this page helpful