Uploaded image for project: 'Core Server'
  1. Core Server
  2. SERVER-28613

Add the $dateToParts and $dateFromParts A/F operators

    XMLWordPrintable

    Details

    • Backwards Compatibility:
      Fully Compatible
    • Epic Link:
    • Sprint:
      Query 2017-07-10
    • Linked BF Score:
      0

      Description

      The new $dateToParts operator simplifies having multiple single date value extraction operators into a single one. Its syntax is:

          { "$project" : {
              "parts" : {
                  "$dateToParts" : {
                      "date" : ISODateValue,
                      "timezone" : timeZoneIdentifier,
                      "iso8601" : boolean
                  }
              }
          } }
      

      The "timezone" argument is optional, and must evaluate to specify an Olson Timezone Identifier such as "Europe/London" or "America/New_York", or, a UTC offset string in the forms: "+03", "-0530", and "+04:45". If you specify a timezone argument it means that the date that you provided will be interpreted as it was in the given time zone.

      The result of the operator is a sub-document with the broken down parts, expressed in the (optionally) given time zone:

          "parts" : {
              "year" : 1978, "month" : 12, "day" : 22,
              "hour" : 9, "minute" : 15, "second" : 0, "millisecond" : 0
          }
      

      $dateToParts also supports a third boolean argument, iso8601. If set to true, instead of year, month, and day, it returns the ISO 8601 isoYear, isoWeekYear, and isoDayOfWeek fields representing an ISO Week Date. With the same date, the example is represented as:

          "parts" : {
              "isoYear" : 1978, "isoWeekYear" : 51, "isoDayOfWeek" : 5,
              "hour" : 9, "minute" : 15, "second" : 0, "millisecond" : 0
          }
      


      The $dateFromParts operator does the opposite of the $dateToParts operator and constructs a new Date value from its constituent parts, with the possibility of interpreting the given values in a different time zone.

      Its syntax is either::

          { "$project" : {
              "date" : {
                  "$dateFromParts": {
                      "year" : yearExpression,
                      "month" : monthExpression,
                      "day" : dayExpression,
                      "hour" : hourExpression,
                      "minute" : minuteExpression,
                      "second" : secondExpression,
                      "millisecond" : millisecondExpression,
                      "timezone" : timezoneExpression
                  }
              }
          } }
      

      or:

          { "$project" : {
              "date" : {
                  "$dateFromParts": {
                      "isoYear" : isoYearExpression,
                      "isoWeekYear" : isoWeekYearExpression,
                      "isoDayOfWeek" : isoDayOfWeekExpression,
                      "hour" : hourExpression,
                      "minute" : minuteExpression,
                      "second" : secondExpression,
                      "millisecond" : millisecondExpression,
                      "timezone" : timezoneExpression
                  }
              }
          } }
      

      Each argument's expression needs to evaluate to a number. This means the source can be either double, NumberInt, NumberLong, or Decimal. Decimal and double values are only supported if they convert to a NumberLong without any data loss.

      Notes

      • Before MongoDB 3.5.12, the argument millisecond to dateFromParts is incorrectly spelled milliseconds.
      • Until SERVER-30547 is resolved, $dateFromParts does not accept an sub-document as argument, and instead requires each single field to be specified.
      • Until SERVER-30523 is resolved, the field values to dateFromParts can not underflow or overflow their expected range. For example, the day field's value needs to be in the range 1..31 and the hour field's value needs to be in the range 0..23.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              derick Derick Rethans
              Reporter:
              ian.whalen Ian Whalen
              Participants:
              Votes:
              1 Vote for this issue
              Watchers:
              6 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: