From 1d9b12ec26db90818b4ea688bf575ec0ded3c063 Mon Sep 17 00:00:00 2001 From: Pavithra Vetriselvan Date: Thu, 7 Sep 2017 11:37:39 -0400 Subject: [PATCH 1/2] DOCS-10474 created dateFromString aggregation page with method descriptions and examples --- .../operator/aggregation/dateFromString.txt | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 source/reference/operator/aggregation/dateFromString.txt diff --git a/source/reference/operator/aggregation/dateFromString.txt b/source/reference/operator/aggregation/dateFromString.txt new file mode 100644 index 00000000000..5b2e246e56a --- /dev/null +++ b/source/reference/operator/aggregation/dateFromString.txt @@ -0,0 +1,93 @@ +============================= +$dateFromString (aggregation) +============================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. expression:: $dateFromString + + .. versionadded:: 3.6 + + Converts a datetime string to a date object + + The :expression:`$dateFromString` expression has the following syntax: + + .. code-block:: javascript + + { $dateFromString: { dateString: , : } } + + The :pipeline:`$dateToString` takes a document with the following fields: + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Field + - Description + + * - ``dateString`` + + - The datetime string to convert to a date object. It should be in + ``ISODate`` format. See :doc:`Date ` for + more information on datetime format. + + This argument should not include a 'Z' at the end, which indicates + Zulu Time and would conflict with the timezone argument. + + * - ``timezone`` + + - Optional. The timezone to use to format the date. + + ```` 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 during runtime, the ``dateStringExpression`` or ``tzExpression`` evaluate +to null, missing or undefined, the result of the $dateToParts expression is +null. + +Example +------- + +Consider the following :term:`aggregate` method on the ``tz`` collection: + +.. code-block:: javascript + + db.tz.aggregate( { date: { + $dateFromString: { + dateString: '2017-02-08T12:10:40.787', + timezone: 'America/New_York' + } + } } ); + +The above aggregation uses the :expression:`$dateFromString` to return +the date object below: + +.. code-block:: javascript + + { date: ISODate( “2017-02-08T17:10:40.787Z” ) } From d2530d22c42c16613dabd1390df2a986d30ad38a Mon Sep 17 00:00:00 2001 From: Pavithra Vetriselvan Date: Thu, 7 Sep 2017 11:45:59 -0400 Subject: [PATCH 2/2] DOCS-10474 created dateFromString aggregation page with method descriptions and examples --- .../ref-toc-aggregation-operators.yaml | 5 + .../operator/aggregation/dateFromString.txt | 98 ++++++++++++++----- source/release-notes/3.6.txt | 5 + 3 files changed, 86 insertions(+), 22 deletions(-) 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 index 5b2e246e56a..e6d020111a4 100644 --- a/source/reference/operator/aggregation/dateFromString.txt +++ b/source/reference/operator/aggregation/dateFromString.txt @@ -17,15 +17,15 @@ Definition .. versionadded:: 3.6 - Converts a datetime string to a date object + Converts a date/time string to a date object. The :expression:`$dateFromString` expression has the following syntax: .. code-block:: javascript - { $dateFromString: { dateString: , : } } + { $dateFromString: { dateString: , } } - The :pipeline:`$dateToString` takes a document with the following fields: + The :pipeline:`$dateFromString` takes a document with the following fields: .. list-table:: :header-rows: 1 @@ -36,16 +36,24 @@ Definition * - ``dateString`` - - The datetime string to convert to a date object. It should be in - ``ISODate`` format. See :doc:`Date ` for - more information on datetime format. + - The date/time string to convert to a date object. See + :doc:`Date ` for + more information on date/time formats. - This argument should not include a 'Z' at the end, which indicates - Zulu Time and would conflict with the timezone argument. + .. note:: + + If specifying the ``timezone`` option to the operator, do not include + time zone information in the ``dateString``. * - ``timezone`` - - Optional. The timezone to use to format the date. + - 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: @@ -67,27 +75,73 @@ Definition For more information on expressions, see :ref:`aggregation-expressions`. -If during runtime, the ``dateStringExpression`` or ``tzExpression`` evaluate -to null, missing or undefined, the result of the $dateToParts expression is -null. +If the ``dateStringExpression`` or ``tzExpression`` evaluate to null, missing or +undefined, the result of the $dateFromString expression is null. Example ------- -Consider the following :term:`aggregate` method on the ``tz`` collection: +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.tz.aggregate( { date: { - $dateFromString: { - dateString: '2017-02-08T12:10:40.787', - timezone: 'America/New_York' - } - } } ); + db.logmessages.aggregate( [ { + $project: { + date: { + $dateFromString: { + dateString: '$date', + timezone: 'America/New_York' + } + } + } + } ] ) -The above aggregation uses the :expression:`$dateFromString` to return -the date object below: +The above aggregation returns the following documents and converts each ``date`` field +to the Eastern Time Zone: .. code-block:: javascript - { date: ISODate( “2017-02-08T17:10:40.787Z” ) } + { "_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 ~~~~~~~~~~~~~~~~~~~~~~~~