$dateToParts (aggregation)
On this page
Definition
$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
andmillisecond
.You can set the
iso8601
property totrue
to return the parts representing an ISO week date instead. This will return a document where the properties areisoWeekYear
,isoWeek
,isoDayOfWeek
,hour
,minute
,second
andmillisecond
.The
$dateToParts
expression has the following syntax:{ $dateToParts: { 'date' : <dateExpression>, 'timezone' : <timezone>, 'iso8601' : <boolean> } } The
$dateToParts
takes a document with the following fields:FieldRequired/OptionalDescriptiondate
RequiredThe 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
OptionalThe 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"
, ora 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
OptionalIf set totrue
, modifies the output document to use ISO week date fields. Defaults tofalse
.
Behavior
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 }
Example
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 } }