[SERVER-28613] Add the $dateToParts and $dateFromParts A/F operators Created: 04/Apr/17  Updated: 06/Dec/17  Resolved: 29/Jun/17

Status: Closed
Project: Core Server
Component/s: Aggregation Framework, Querying
Affects Version/s: None
Fix Version/s: 3.5.10

Type: Task Priority: Major - P3
Reporter: Ian Whalen (Inactive) Assignee: Derick Rethans
Resolution: Done Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
Documented
is documented by DOCS-10475 Docs for SERVER-28613: Add the $dateT... Closed
Duplicate
is duplicated by SERVER-16347 Support for date aggregation operator... Closed
Related
related to SERVER-29208 Add the $dateFromString A/F operator ... Closed
Backwards Compatibility: Fully Compatible
Sprint: Query 2017-07-10
Participants:
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.


 Comments   
Comment by Githook User [ 30/Jun/17 ]

Author:

{u'username': u'derickr', u'name': u'Derick Rethans', u'email': u'github@derickrethans.nl'}

Message: SERVER-28613: Fixed memory leak while fetching a timelib_time.
Branch: master
https://github.com/mongodb/mongo/commit/fbcf295fff8fe1723120345126be90a49d7b6d14

Comment by Githook User [ 29/Jun/17 ]

Author:

{u'username': u'derickr', u'name': u'Derick Rethans', u'email': u'github@derickrethans.nl'}

Message: SERVER-28613: Add $dateToParts and $dateFromParts aggregation framework operators
Branch: master
https://github.com/mongodb/mongo/commit/5811a6ac496c6368e4fc4d9a5c8ed51a8b37833a

Generated at Thu Feb 08 04:18:36 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.