The $dateFromString operator converts text date values into BSON Date objects inside aggregation pipelines. Use it when imports, APIs, or legacy systems store timestamps as strings and you need proper dates for sorting, indexing, or operators like $dateDiff and $dateAdd.
Text → BSON Date.
dateString field.
ISO 8601 or custom.
Optional Olson zone.
onError, onNull.
Parse vs generic cast.
In MongoDB’s aggregation framework, the $dateFromString operator parses a string into a BSON Date. For example, if a document stores createdAt: "2024-06-15T10:30:00Z" as text, $dateFromString can turn it into a real date value for range queries, chronological sorting, or elapsed-time calculations.
$dateFromString returns a Date, not a string. When you omit format, MongoDB expects ISO 8601 (e.g. "2024-06-15" or "2024-06-15T10:30:00Z"). For other layouts like "06/15/2024", supply a matching format pattern.
The $dateFromString operator takes an object with a required string and optional parsing options:
{
$dateFromString: {
dateString: <stringExpression>,
format: <stringExpression>,
timezone: <stringExpression>,
onError: <expression>,
onNull: <expression>
}
}dateString — required; the text value to parse (field reference or literal).format — optional; pattern using format specifiers like %Y (year), %m (month), %d (day). Omit for ISO 8601.timezone — optional Olson timezone ID when the string has no offset.onError — optional fallback when parsing fails (invalid format or date).onNull — optional fallback when dateString is null or missing.Date stored in UTC internally.%Y — four-digit year (2024)%m — month 01–12%d — day 01–31%H — hour 00–23%M — minute 00–59%S — second 00–60%L — millisecond 000–999to: "date"; less control over format| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | dateString |
| Return type | BSON Date |
| Default parsing | ISO 8601 when format is omitted |
| MongoDB version | 3.6+ |
{
$dateFromString: {
dateString: "2024-06-15T10:30:00Z"
}
}No format needed
{
$dateFromString: {
dateString: "$createdAtStr"
}
}Parse a document field
{
$dateFromString: {
dateString: "06/15/2024",
format: "%m/%d/%Y"
}
}US-style date string
{
$dateFromString: {
dateString: "$rawDate",
onError: null,
onNull: null
}
}Null on bad input
Parse ISO strings, handle US date formats, add timezone context, and safely migrate messy import data with $dateFromString.
Use a logs collection where timestamps were imported as ISO text.
Suppose you have a logs collection with string timestamps:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"event": "login",
"timestampStr": "2024-06-15T10:30:00Z"
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"event": "logout",
"timestampStr": "2024-06-16T18:45:00Z"
}
]Parse the string field into a BSON Date without specifying a format:
db.logs.aggregate([
{
$project: {
event: 1,
timestampStr: 1,
timestamp: {
$dateFromString: {
dateString: "$timestampStr"
}
}
}
}
])format is omitted, MongoDB parses standard ISO 8601 strings.Z suffix means UTC; the result is stored as a BSON Date.timestamp or use $dateDiff for elapsed time.Custom formats, timezone interpretation, and safe parsing for messy data.
Handle US-style dates like "06/15/2024" with an explicit format pattern:
db.orders.aggregate([
{
$project: {
orderId: 1,
orderDateStr: 1,
orderDate: {
$dateFromString: {
dateString: "$orderDateStr",
format: "%m/%d/%Y"
}
}
}
}
])
// orderDateStr: "06/15/2024" → ISODate("2024-06-15T00:00:00.000Z")The format string must match the layout of dateString exactly. Use %H:%M:%S extensions when the string includes time components, e.g. format: "%m/%d/%Y %H:%M".
When the string has no UTC offset, interpret it in a specific timezone:
db.events.aggregate([
{
$project: {
title: 1,
localStartStr: 1,
startsAt: {
$dateFromString: {
dateString: "$localStartStr",
format: "%Y-%m-%d %H:%M",
timezone: "America/Chicago"
}
}
}
}
])
// localStartStr: "2024-07-04 09:00" in Central Time → UTC equivalentThe timezone field tells MongoDB which Olson zone to use when the string lacks an explicit offset. This is important for daylight saving and regional event schedules.
During migration, some rows may have bad date text. Use onError and onNull instead of failing the pipeline:
db.imports.aggregate([
{
$project: {
name: 1,
rawDate: 1,
parsedDate: {
$dateFromString: {
dateString: "$rawDate",
format: "%d-%b-%Y",
onError: null,
onNull: null
}
}
}
},
{
$match: {
parsedDate: { $ne: null }
}
}
])
// "15-Jun-2024" → valid Date; "not-a-date" → null (filtered out)onError catches parse failures; onNull handles missing values. Filter or flag bad rows in a follow-up stage rather than stopping the entire aggregation.
onError to quarantine invalid rows without crashing the pipeline.$dateFromString WorksdateString is evaluated per document — a field reference or literal text value.
MongoDB applies format (or ISO 8601 default) and optional timezone.
On failure, onError or onNull provides a fallback; otherwise an error is thrown.
Use with $match date ranges, $dateDiff, indexes, and any operator that expects a BSON Date.
The $dateFromString operator is the standard way to turn text timestamps into BSON dates in MongoDB aggregation pipelines. It supports ISO 8601 out of the box and custom format patterns for legacy or locale-specific layouts.
Pair it with $dateFromParts when your data uses numeric components instead of strings, and use onError / onNull when importing messy data. After parsing, index the new date field and replace string columns when possible.
Date at insert time when you control the schemaformat exactly to your string layoutonError and onNull during bulk imports$dateFromString with $dateToString (format out, not in)timezone when strings lack an offset$dateFromStringUse these points when parsing date strings in MongoDB.
Text → BSON Date.
PurposedateString.
SyntaxOmit format for ISO.
FormatonError, onNull.
OptionParse vs format out.
ImportantMove on to $dateSubtract to shift dates backward, or review $dateFromParts when your data uses numeric components.
5 people found this page helpful