diff --git a/source/includes/ref-toc-aggregation-operators.yaml b/source/includes/ref-toc-aggregation-operators.yaml index bc6f43fa004..c861dab5dba 100644 --- a/source/includes/ref-toc-aggregation-operators.yaml +++ b/source/includes/ref-toc-aggregation-operators.yaml @@ -86,6 +86,11 @@ description: | Accepts either three expressions in an ordered list or three named parameters. --- +name: :expression:`$dateFromString` +file: /reference/operator/aggregation/dateFromString +description: | + Returns a date/time as a date object. +--- name: :expression:`$dateToString` file: /reference/operator/aggregation/dateToString description: | diff --git a/source/reference/operator/aggregation/dateFromString.txt b/source/reference/operator/aggregation/dateFromString.txt new file mode 100644 index 00000000000..e6d020111a4 --- /dev/null +++ b/source/reference/operator/aggregation/dateFromString.txt @@ -0,0 +1,147 @@ +============================= +$dateFromString (aggregation) +============================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. expression:: $dateFromString + + .. versionadded:: 3.6 + + Converts a date/time string to a date object. + + The :expression:`$dateFromString` expression has the following syntax: + + .. code-block:: javascript + + { $dateFromString: { dateString: , } } + + The :pipeline:`$dateFromString` takes a document with the following fields: + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Field + - Description + + * - ``dateString`` + + - The date/time string to convert to a date object. See + :doc:`Date ` for + more information on date/time formats. + + .. note:: + + If specifying the ``timezone`` option to the operator, do not include + time zone information in the ``dateString``. + + * - ``timezone`` + + - Optional. The time zone to use to format the date. + + .. note:: + + If the ``dateString`` argument is formatted like + '2017-02-08T12:10:40.787Z', in which the 'Z' at the end indicates Zulu + time (UTC time zone), you cannot specify the ``timezone`` argument. + + ```` allows for the following options and expressions + that evaluate to them: + + - 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"``, or + + - The strings `"Z"`, `"UTC"`, or `"GMT"` + + For more information on expressions, see + :ref:`aggregation-expressions`. + +If the ``dateStringExpression`` or ``tzExpression`` evaluate to null, missing or +undefined, the result of the $dateFromString expression is null. + +Example +------- + +Consider a collection ``logmessages`` that contains the following documents: + +.. code-block:: javascript + + { _id: 1, date: "2017-02-08T12:10:40.787", timezone: "America/New_York", message: "Step 1: Started" }, + { _id: 2, date: "2017-02-08", timezone: "-05:00", message: "Step 1: Ended" }, + { _id: 3, message: " Step 1: Ended " }, + { _id: 4, date: "2017-02-09", timezone: "Europe/London", message: "Step 2: Started"} + { _id: 5, date: "2017-02-09T03:35:02.055", timezone: "+0530", message: "Step 2: In Progress"} + +The following aggregation uses $dateFromString to convert the ``date`` value +to a date object: + +.. code-block:: javascript + + db.logmessages.aggregate( [ { + $project: { + date: { + $dateFromString: { + dateString: '$date', + timezone: 'America/New_York' + } + } + } + } ] ) + +The above aggregation returns the following documents and converts each ``date`` field +to the Eastern Time Zone: + +.. code-block:: javascript + + { "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") } + { "_id" : 2, "date" : ISODate("2017-02-08T05:00:00Z") } + { "_id" : 3, "date" : null } + { "_id" : 4, "date" : ISODate("2017-02-09T05:00:00Z") } + { "_id" : 5, "date" : ISODate("2017-02-09T08:35:02.055Z") } + +The ``timezone`` argument can also be provided through a document field instead of a +hard coded argument. For example: + +.. code-block:: javascript + + db.logmessages.aggregate( [ { + $project: { + date: { + $dateFromString: { + dateString: '$date', + timezone: '$timezone' + } + } + } + } ] ) + +The above aggregation returns the following documents and converts each ``date`` field +to their respective UTC representations. + +.. code-block:: javascript + + { "_id" : 1, "date" : ISODate("2017-02-08T17:10:40.787Z") } + { "_id" : 2, "date" : ISODate("2017-02-08T05:00:00Z") } + { "_id" : 3, "date" : null } + { "_id" : 4, "date" : ISODate("2017-02-09T00:00:00Z") } + { "_id" : 5, "date" : ISODate("2017-02-08T22:05:02.055Z") } + diff --git a/source/release-notes/3.6.txt b/source/release-notes/3.6.txt index 1c05de819d3..ac5881c393e 100644 --- a/source/release-notes/3.6.txt +++ b/source/release-notes/3.6.txt @@ -47,6 +47,11 @@ New Aggregation Operators - Combines multiple documents into a single document. + * - :expression:`$dateFromString` + + - Converts a date/time string to a date object. + + New Aggregation Variable ~~~~~~~~~~~~~~~~~~~~~~~~