The $dateFromParts operator assembles a BSON Date from separate numeric fields such as year, month, and day. Use it when legacy data stores date components in different columns, or when you need to build a timestamp inside an aggregation pipeline without string parsing.
Parts → BSON Date.
year, month, day.
hour, minute, second.
Optional Olson zone.
Legacy data, ETL.
Build vs split.
In MongoDB’s aggregation framework, the $dateFromParts operator constructs a single BSON Date from integer components. For example, if a document stores birthYear: 1995, birthMonth: 8, and birthDay: 15, $dateFromParts can combine them into one date value for sorting, filtering, or further date math with operators like $dateAdd or $dateDiff.
$dateFromParts returns a Date, not a number. At minimum you must supply year, month, and day. Omitted time fields default to midnight (00:00:00.000). Requires MongoDB 5.0+.
The $dateFromParts operator takes an object with date and optional time fields:
{
$dateFromParts: {
year: <intExpression>,
month: <intExpression>,
day: <intExpression>,
hour: <intExpression>,
minute: <intExpression>,
second: <intExpression>,
millisecond: <intExpression>,
timezone: <stringExpression>
}
}year, month, day — required; use 1–12 for month and valid day for the given month.hour, minute, second, millisecond — optional; default to 0.timezone — optional Olson timezone ID (e.g. "UTC", "America/Chicago").isoWeekYear, isoWeek, isoDayOfWeek instead of calendar year/month/day.Date stored in UTC internally.| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (date) |
| Required fields | year, month, day |
| Return type | BSON Date |
| Default time | 00:00:00.000 when hour/minute/second omitted |
| MongoDB version | 5.0+ |
{
$dateFromParts: {
year: 2024,
month: 6,
day: 15
}
}June 15, 2024 at midnight UTC
{
$dateFromParts: {
year: "$y",
month: "$m",
day: "$d"
}
}Combine document fields
{
$dateFromParts: {
year: 2024,
month: 1,
day: 1,
hour: 14,
minute: 30
}
}Include hour and minute
{
$dateFromParts: {
year: 2024,
month: 7,
day: 4,
hour: 9,
timezone: "America/New_York"
}
}Local time in a zone
Build dates from separate fields, add time components, construct timezone-aware timestamps, and normalize legacy imports with $dateFromParts.
Use a users collection where birth date parts are stored as separate integers.
Suppose you have a users collection with year, month, and day stored separately:
[
{
"_id": ObjectId("609c26812e9274a86871bc6a"),
"name": "Alice",
"birthYear": 1995,
"birthMonth": 8,
"birthDay": 15
},
{
"_id": ObjectId("609c26812e9274a86871bc6b"),
"name": "Bob",
"birthYear": 2001,
"birthMonth": 3,
"birthDay": 22
}
]Construct a single birthDate field from the three integer fields:
db.users.aggregate([
{
$project: {
name: 1,
birthYear: 1,
birthMonth: 1,
birthDay: 1,
birthDate: {
$dateFromParts: {
year: "$birthYear",
month: "$birthMonth",
day: "$birthDay"
}
}
}
}
])Date you can sort, compare, or pass to $dateDiff.Add time of day, respect timezones, and migrate legacy CSV-style data.
Build an appointment timestamp when date and time are stored as separate numbers:
db.appointments.aggregate([
{
$project: {
patient: 1,
scheduledAt: {
$dateFromParts: {
year: "$apptYear",
month: "$apptMonth",
day: "$apptDay",
hour: "$apptHour",
minute: "$apptMinute"
}
}
}
}
])
// apptYear: 2024, apptMonth: 6, apptDay: 10, apptHour: 14, apptMinute: 30
// → ISODate("2024-06-10T14:30:00.000Z")Each time component is optional beyond the required date parts. Use second and millisecond when you need finer precision for logging or event ordering.
Interpret local date/time in a specific timezone before storing as UTC:
db.events.aggregate([
{
$project: {
title: 1,
startsAt: {
$dateFromParts: {
year: 2024,
month: 7,
day: 4,
hour: 9,
minute: 0,
timezone: "America/New_York"
}
}
}
}
])
// 9:00 AM Eastern on July 4, 2024 → stored as UTC equivalentWithout timezone, parts are treated as UTC. With an Olson ID, MongoDB interprets the components in that zone, which matters for daylight saving and regional reporting.
During ETL, replace separate date columns with a proper Date field and drop the old parts:
db.legacy_orders.aggregate([
{
$set: {
orderDate: {
$dateFromParts: {
year: "$orderYear",
month: "$orderMonth",
day: "$orderDay"
}
}
}
},
{
$unset: ["orderYear", "orderMonth", "orderDay"]
}
])Use $set (or $addFields) to create the normalized date, then $unset redundant fields. After migration, index orderDate for efficient range queries.
$facet or dashboard queries.$dateFromParts Worksyear, month, day, and optional time fields are resolved per document — literals or field references.
MongoDB validates the combination and applies timezone if provided.
The result is stored in the field you define — ready for sorting, indexing, or date math.
Use with $dateDiff, $dateAdd, $match on date ranges, or export to applications expecting ISO dates.
The $dateFromParts operator is the clearest way to build BSON dates from numeric components in MongoDB aggregation pipelines. It avoids fragile string concatenation and manual parsing when your data already stores year, month, and day as separate values.
Pair it with $dateToParts when you need to split dates back into components, or $dateFromString when your source is a formatted string. Always validate that month and day values are sensible, and ensure your MongoDB deployment is version 5.0 or later.
timezone when local calendar semantics matterDate field after normalization$dateFromParts over string concat + $dateFromString for numeric parts$dateDiff once you have a proper BSON date$dateFromParts on MongoDB versions before 5.0$dateFromParts with $dateToParts$dateFromPartsUse these points when constructing dates from components in MongoDB.
Parts → BSON Date.
Purposeyear, month, day.
SyntaxNot a number.
OutputOptional Olson ID.
OptionBuild vs split.
ImportantMove on to $dateFromString to parse formatted date strings, or review $dateDiff to measure time between dates.
5 people found this page helpful