$dateToParts (aggregation)¶

On this page

Definition
Behavior
Example

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 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:

copy

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

The $dateToParts takes a document with the following fields:

Field Required/Optional Description

date

Required

Changed in version 3.6.

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.

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:

copy

{
   "_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:

copy

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:

copy

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

Example¶

Consider a sales collection with the following document:

copy

{
  "_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.

copy

 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:

copy

{
   "_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
   }
}

← $dateFromParts (aggregation) $dateFromString (aggregation) →