$dateFromString is a MongoDB aggregation expression that parses a date string into a BSON Date. Use it when dates arrive as text and you need a real date for sorting, filtering, or date math.
Remember
$dateFromString = text → BSON Date
{ $dateFromString: {
dateString: <expression>, // required
format: <string>, // optional
timezone: <string>, // optional
onError: <expression>, // optional fallback
onNull: <expression> // optional fallback
}
}
no format → ISO-style parse when possible
bad string → error (unless onError is set)
null / missing → null (unless onNull is set)
Set dateString to the field (or expression) that holds the text.
Add format when the string is custom (for example "%d/%m/%Y").
Optionally set onError / onNull so messy rows do not fail the pipeline.
Piece
Required?
Role
dateString
Yes
Text to parse
format
No
Pattern when the string is not ISO-like
onError / onNull
No
Fallbacks for bad or missing text
Pseudocode
Pseudocode
for each document:
s = evaluate(dateString)
if s is null or missing:
result = onNull if set, else null
else:
try:
result = parse(s, format?, timezone?)
catch:
result = onError if set, else error // pipeline fails
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while parsing date strings.
One event stores the time as text: "2026-10-02T09:15:00Z". We want a real BSON Date.
Calculation
Document:
{ when_text: "2026-10-02T09:15:00Z" }
$dateFromString: { dateString: "$when_text" }
Step by step:
1) Read the string field
2) Parse as ISO-style date/time (UTC via Z)
3) Store a BSON Date
Result:
ISODate("2026-10-02T09:15:00.000Z")
Now you can sort, $match by range, or use date math.
Code
MongoDB Examples
We store one event with two date strings: an ISO value and a day/month/year value. First we insert the data, then we parse each style. Run these in mongosh after inserting the sample data once.
Example 1 — Sample Data
Imagine one event with two text dates: an ISO timestamp and a day/month/year label. We save them in a collection named events.
Text in → Date out:
when_text: "2026-10-02T09:15:00Z" → parse without format
local_text: "02/10/2026" → parse with "%d/%m/%Y"
Until you parse them, MongoDB treats both as plain strings
(so date-range queries and date math will not work as expected).
How It Works
Insert once.insertOne adds a single event document to events.
MongoDB stores fields as written. Both date fields are still strings, not Dates.
find() shows the same shape. What you inserted is what you get back—ready for $dateFromString next.
Example 2 — Parse ISO Text
Goal: turn when_text into a real BSON Date using the default ISO-style parse.
Same stored document. Still using local_text: "02/10/2026" from Example 1.
Match the pattern.%d/%m/%Y means day, month, year with slashes.
Parse to midnight UTC. With no time in the string, the time part is 00:00:00.000Z.
Easy check. Day 02, month 10, year 2026 → October 2, 2026.
Edge Cases & Pitfalls
Check these before using $dateFromString in production pipelines.
format
Custom text needs a matching format
Strings like "02/10/2026" are ambiguous. Set format (for example "%d/%m/%Y") so day and month are not swapped.
error
Bad strings can fail the pipeline
Without onError, a single unparseable value can stop the aggregation. Use onError: null (or another fallback) on messy imports.
tz
Do not mix Z with timezone
If the string already ends with Z (UTC), do not also pass timezone. Pick one source of truth for the zone.
null
Null and missing become null
Missing dateString returns null unless you set onNull. That is quieter than a parse error, but still not a Date.
Analysis
Performance Notes
Approach
Cost
Best for
$dateFromString alone
Per-document parse
ISO / simple date text fields
+ custom format
Still O(docs)
Locale-style strings (d/m/Y, etc.)
+ onError / onNull
Tiny extra branching
Dirty imports that must keep running
Parsing is cheap compared with large sorts or joins. If you reuse the Date often, consider converting once and storing a real Date field. Filter early with $match when only some rows need parsing.
Remember
Key Takeaways
Role: text date → BSON Date in aggregation.
ISO: often works with only dateString.
Custom: set format (for example "%d/%m/%Y").
Safety: use onError / onNull on messy data.
One line:$dateFromString answers “turn this date text into a real Date”—with optional format and safe fallbacks.
Frequently Asked Questions
$dateFromString converts a date/time string into a BSON Date inside aggregation. Use it when dates are stored as text—CSV imports, APIs, or legacy fields—and you need a real Date for sorting or date math.
Use { $dateFromString: { dateString: <expression>, format: <string>, timezone: <string>, onError: <expression>, onNull: <expression> } }. Only dateString is required. If format is omitted, MongoDB tries ISO-style parsing.
$dateFromString parses one text value. $dateFromParts builds a date from separate numeric fields like year, month, and day. Pick the operator that matches how your data is stored.
onError returns a fallback when parsing fails. onNull returns a fallback when dateString is null or missing. Without onError, a bad string can fail the whole pipeline.
%Y is year, %m month, %d day, %H hour, %M minute, %S second. Example: format "%d/%m/%Y" matches "02/10/2026".
Similar idea—text in, Date out—but MongoDB uses its own format rules and options. Run it in the aggregation pipeline, not as a standalone find() filter.
