Docs Menu
Docs Home
/
MongoDB Manual
/ / /

$dateToParts (aggregation)

On this page

  • Definition
  • Behavior
  • Example
$dateToParts

New in version 3.6.

Returns a document that contains the constituent parts of a given BSON Date value as individual properties. The properties returned are year, month, day, hour, minute, second and millisecond.

You can set the iso8601 property to true to return the parts representing an ISO week date instead. This will return a document where the properties are isoWeekYear, isoWeek, isoDayOfWeek, hour, minute, second and millisecond.

The $dateToParts expression has the following syntax:

{
$dateToParts: {
'date' : <dateExpression>,
'timezone' : <timezone>,
'iso8601' : <boolean>
}
}

The $dateToParts takes a document with the following fields:

Field
Required/Optional
Description
date
Required
The input date for which to return parts. <dateExpression> can be any expression that resolves to a Date, a Timestamp, or an ObjectID. For more information on expressions, see Expressions.
timezone
Optional

The timezone to use to format the date. By default, $dateToParts uses UTC.

<timezone> can be any expression that evaluates to a string whose value is either:

  • an Olson Timezone Identifier, such as "Europe/London" or "America/New_York", or

  • a UTC offset in the form:

    • +/-[hh]:[mm], e.g. "+04:45", or

    • +/-[hh][mm], e.g. "-0530", or

    • +/-[hh], e.g. "+03".

For more information on expressions, see Expressions.

iso8601
Optional
If set to true, modifies the output document to use ISO week date fields. Defaults to false.

When using an Olson Timezone Identifier in the <timezone> field, MongoDB applies the DST offset if applicable for the specified timezone.

For example, consider a sales collection with the following document:

{
"_id" : 1,
"item" : "abc",
"price" : 20,
"quantity" : 5,
"date" : ISODate("2017-05-20T10:24:51.303Z")
}

The following aggregation illustrates how MongoDB handles the DST offset for the Olson Timezone Identifier. The example uses the $hour and $minute operators to return the corresponding portions of the date field:

db.sales.aggregate([
{
$project: {
"nycHour": {
$hour: { date: "$date", timezone: "-05:00" }
},
"nycMinute": {
$minute: { date: "$date", timezone: "-05:00" }
},
"gmtHour": {
$hour: { date: "$date", timezone: "GMT" }
},
"gmtMinute": {
$minute: { date: "$date", timezone: "GMT" } },
"nycOlsonHour": {
$hour: { date: "$date", timezone: "America/New_York" }
},
"nycOlsonMinute": {
$minute: { date: "$date", timezone: "America/New_York" }
}
}
}])

The operation returns the following result:

{
"_id": 1,
"nycHour" : 5,
"nycMinute" : 24,
"gmtHour" : 10,
"gmtMinute" : 24,
"nycOlsonHour" : 6,
"nycOlsonMinute" : 24
}

Consider a sales collection with the following document:

{
"_id" : 2,
"item" : "abc",
"price" : 10,
"quantity" : 2,
"date" : ISODate("2017-01-01T01:29:09.123Z")
}

The following aggregation uses $dateToParts to return a document that contains the constituent parts of the date field.

db.sales.aggregate([
{
$project: {
date: {
$dateToParts: { date: "$date" }
},
date_iso: {
$dateToParts: { date: "$date", iso8601: true }
},
date_timezone: {
$dateToParts: { date: "$date", timezone: "America/New_York" }
}
}
}])

The operation returns the following result:

{
"_id" : 2,
"date" : {
"year" : 2017,
"month" : 1,
"day" : 1,
"hour" : 1,
"minute" : 29,
"second" : 9,
"millisecond" : 123
},
"date_iso" : {
"isoWeekYear" : 2016,
"isoWeek" : 52,
"isoDayOfWeek" : 7,
"hour" : 1,
"minute" : 29,
"second" : 9,
"millisecond" : 123
},
"date_timezone" : {
"year" : 2016,
"month" : 12,
"day" : 31,
"hour" : 20,
"minute" : 29,
"second" : 9,
"millisecond" : 123
}
}

Back

$dateSubtract