$dateToParts (aggregation)

Definition

• $dateToParts

New in version 3.6.

Returns a document that contains the constituent parts of a givenBSON Date value as individual properties. The properties returnedare year, month, day, hour, minute, secondand millisecond.

You can set the iso8601 property to true to return the partsrepresenting anISO week dateinstead. This will return a document where the properties areisoWeekYear, 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:

FieldRequired/OptionalDescriptiondateRequired

Changed in version 3.6.

The input date for which to return parts.<dateExpression> can be anyexpression that resolves to aDate, aTimestamp, or anObjectID. For moreinformation on expressions, seeExpressions.timezoneOptionalThe timezone to use to format the date. By default,$dateToParts uses UTC.

<timezone> can be any expression that evaluates to a string whosevalue 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, seeExpressions.iso8601OptionalIf set to true, modifies the output document to use ISOweek date fields. Defaults to false.

Behavior

When using an Olson Timezone Identifier in the <timezone>field, MongoDB applies the DST offsetif 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 DSToffset for the Olson Timezone Identifier. The example uses the$hour and $minute operators to return thecorresponding 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 adocument 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
   }
}