Skip to content

Commit 160d169

Browse files
steverenkay-kim
steveren
authored and
kay-kim
committed
DOCS-8823: new ISO date agg operators
1 parent a6d2a40 commit 160d169

File tree

6 files changed

+348
-1
lines changed

6 files changed

+348
-1
lines changed

‎source/includes/fact-iso-date-objects.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
The argument can be any valid :ref:`expression
2+
<aggregation-expressions>` that resolves to a
3+
:doc:`BSON ISODate object </reference/bson-types>`,
4+
a :doc:`BSON Timestamp object </reference/bson-types>`,
5+
or a :doc:`Date object </reference/method/Date/>`.

‎source/includes/ref-toc-aggregation-date.yaml

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,4 +58,25 @@ name: :expression:`$dateToString`
5858
file: /reference/operator/aggregation/dateToString
5959
description: |
6060
Returns the date as a formatted string.
61-
...
61+
---
62+
name: :expression:`$isoDayOfWeek`
63+
file: /reference/operator/aggregation/isoDayOfWeek
64+
description: |
65+
Returns the weekday number in ISO 8601 format, ranging from
66+
``1`` (for Monday) to ``7`` (for Sunday).
67+
---
68+
name: :expression:`$isoWeek`
69+
file: /reference/operator/aggregation/isoWeek
70+
description: |
71+
Returns the week number in ISO 8601 format, ranging
72+
from ``1`` to ``53``. Week
73+
numbers start at ``1`` with the week (Monday through Sunday)
74+
that contains the year's first Thursday.
75+
---
76+
name: :expression:`$isoWeekYear`
77+
file: /reference/operator/aggregation/isoWeekYear
78+
description: |
79+
Returns the year number in ISO 8601 format. The year starts
80+
with the Monday of week 1 (ISO 8601) and ends with the Sunday of the
81+
last week (ISO 8601).
82+
...

‎source/reference/operator/aggregation/dateToString.txt

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,23 @@ The following format specifiers are available for use in the
9494
- Percent Character as a Literal
9595
- ``%``
9696

97+
.. versionadded:: 3.4
98+
99+
.. list-table::
100+
:widths: 20 60 20
101+
102+
* - ``%G``
103+
- Year in ISO 8601 format
104+
- ``0000``-``9999``
105+
106+
* - ``%V``
107+
- Week of Year in ISO 8601 format
108+
- ``1``-``53``
109+
110+
* - ``%u``
111+
- Day of week number in ISO 8601 format (1-Sunday, 7-Saturday)
112+
- ``1``-``7``
113+
97114
Example
98115
-------
99116

‎source/reference/operator/aggregation/isoDayOfWeek.txt

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
===========================
2+
$isoDayOfWeek (aggregation)
3+
===========================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. expression:: $isoDayOfWeek
17+
18+
.. versionadded:: 3.4
19+
20+
Returns the weekday number in ISO 8601 format, ranging from
21+
``1`` (for Monday) to ``7`` (for Sunday).
22+
23+
:expression:`$isoDayOfWeek` has the following
24+
:ref:`operator expression syntax <aggregation-expressions>`:
25+
26+
.. code-block:: javascript
27+
28+
{ $isoDayOfWeek: <date expression> }
29+
30+
.. include:: /includes/fact-iso-date-objects.rst
31+
32+
Behavior
33+
--------
34+
35+
.. list-table::
36+
:header-rows: 1
37+
:widths: 90 10
38+
39+
* - Example
40+
- Result
41+
42+
* - ``{ $isoDayOfWeek: new Date("2016-01-01") }``
43+
44+
- 5
45+
46+
* - ``{ $isoDayOfWeek: new Date("Jan 7, 2003") }``
47+
48+
- 2
49+
50+
* - ``{ $isoDayOfWeek: new Date("August 14, 2011") }``
51+
52+
- 7
53+
54+
* - ``{ $isoDayOfWeek: ISODate("1998-11-07T00:00:00Z") }``
55+
56+
- 6
57+
58+
* - ``{ $isoDayOfWeek: "March 28, 1976" }``
59+
60+
- ``error``
61+
62+
* - ``{ $isoDayOfWeek: "2009-04-09" }``
63+
64+
- ``error``
65+
66+
.. note:: ``$isoDayOfWeek`` cannot take a string as an argument.
67+
68+
Example
69+
-------
70+
71+
A collection called ``birthdays`` contains the following documents:
72+
73+
.. code-block:: javascript
74+
75+
{ "_id" : 1, "name" : "Betty", "birthday" : ISODate("1993-09-21T00:00:00Z") }
76+
{ "_id" : 2, "name" : "Veronica", "birthday" : ISODate("1981-11-07T00:00:00Z") }
77+
78+
The following operation returns the weekday number for each
79+
``birthday`` field.
80+
81+
.. code-block:: javascript
82+
83+
db.dates.aggregate( [
84+
{
85+
$project: {
86+
_id: 0,
87+
name: "$name",
88+
dayOfWeek: { $isoDayOfWeek: "$birthday" }
89+
}
90+
}
91+
] )
92+
93+
The operation returns the following results:
94+
95+
.. code-block:: javascript
96+
97+
{ "name" : "Betty", "dayOfWeek" : 2 }
98+
{ "name" : "Veronica", "dayOfWeek" : 6 }
99+
100+
.. seealso::
101+
102+
- :doc:`/reference/operator/aggregation/isoWeekYear`
103+
- :doc:`/reference/operator/aggregation/isoWeek`

‎source/reference/operator/aggregation/isoWeek.txt

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
======================
2+
$isoWeek (aggregation)
3+
======================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. expression:: $isoWeek
17+
18+
.. versionadded:: 3.4
19+
20+
Returns the week number in ISO 8601 format, ranging from ``1`` to
21+
``53``. Week numbers start at ``1`` with the week (Monday through
22+
Sunday) that contains the year's first Thursday.
23+
24+
$isoWeek has the following
25+
:ref:`operator expression syntax <aggregation-expressions>`:
26+
27+
.. code-block:: javascript
28+
29+
{ $isoWeek: <date expression> }
30+
31+
.. include:: /includes/fact-iso-date-objects.rst
32+
33+
Behavior
34+
--------
35+
36+
.. list-table::
37+
:header-rows: 1
38+
:widths: 90 10
39+
40+
* - Example
41+
- Result
42+
43+
* - ``{ $isoWeek: new Date("2016-01-01") }``
44+
45+
- 53
46+
47+
* - ``{ $isoWeek: new Date("2015-01-01") }``
48+
49+
- 1
50+
51+
* - ``{ $isoWeek: new Date("August 14, 2011") }``
52+
53+
- 32
54+
55+
* - ``{ $isoWeek: ISODate("1998-11-07T00:00:00Z") }``
56+
57+
- 45
58+
59+
* - ``{ $isoWeek: "March 28, 1976" }``
60+
61+
- ``error``
62+
63+
* - ``{ $isoWeek: "2009-04-09" }``
64+
65+
- ``error``
66+
67+
.. note:: ``$isoWeek`` cannot take a string as an argument.
68+
69+
Example
70+
-------
71+
72+
A collection called ``deliveries`` contains the following documents:
73+
74+
.. code-block:: javascript
75+
76+
{ "_id" : 1, "date" : ISODate("2006-10-24T00:00:00Z"), "city" : "Boston" }
77+
{ "_id" : 2, "date" : ISODate("2011-08-18T00:00:00Z"), "city" : "Detroit" }
78+
79+
The following operation returns the week number for each ``date`` field.
80+
81+
.. code-block:: javascript
82+
83+
db.deliveries.aggregate( [
84+
{
85+
$project: {
86+
_id: 0,
87+
city: "$city",
88+
weekNumber: { $isoWeek: "$date" }
89+
}
90+
}
91+
] )
92+
93+
The operation returns the following results:
94+
95+
.. code-block:: javascript
96+
97+
{ "city" : "Boston", "weekNumber" : 43 }
98+
{ "city" : "Detroit", "weekNumber" : 33 }
99+
100+
.. seealso::
101+
102+
- :doc:`/reference/operator/aggregation/isoDayOfWeek`
103+
- :doc:`/reference/operator/aggregation/isoWeekYear`

‎source/reference/operator/aggregation/isoWeekYear.txt

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
==========================
2+
$isoWeekYear (aggregation)
3+
==========================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. expression:: $isoWeekYear
17+
18+
.. versionadded:: 3.4
19+
20+
Returns the year number in ISO 8601 format. The year starts
21+
with the Monday of week 1 (ISO 8601) and ends with the Sunday of the
22+
last week (ISO 8601).
23+
24+
$isoWeekYear has the following
25+
:ref:`operator expression syntax <aggregation-expressions>`:
26+
27+
.. code-block:: javascript
28+
29+
{ $isoWeekYear: <date expression> }
30+
31+
.. include:: /includes/fact-iso-date-objects.rst
32+
33+
Behavior
34+
--------
35+
36+
.. list-table::
37+
:header-rows: 1
38+
:widths: 90 10
39+
40+
* - Example
41+
- Result
42+
43+
* - ``{ $isoWeekYear: new Date("2016-01-01") }``
44+
45+
- 2015
46+
47+
* - ``{ $isoWeekYear: new Date("2015-01-01") }``
48+
49+
- 2015
50+
51+
* - ``{ $isoWeekYear: new Date("2016-01-04") }``
52+
53+
- 2016
54+
55+
* - ``{ $isoWeekYear: "2016-01-01" }``
56+
57+
- ``error``
58+
59+
.. note:: ``$isoWeekYear`` cannot take a string as an argument.
60+
61+
Example
62+
-------
63+
64+
A collection called ``anniversaries`` contains the following documents:
65+
66+
.. code-block:: javascript
67+
68+
{ "_id" : 1, "date" : ISODate("2016-01-01T00:00:00Z") }
69+
{ "_id" : 2, "date" : ISODate("2016-01-04T00:00:00Z") }
70+
{ "_id" : 3, "date" : ISODate("2015-01-01T00:00:00Z") }
71+
{ "_id" : 4, "date" : ISODate("2014-04-21T00:00:00Z") }
72+
73+
The following operation returns the year number in ISO 8601
74+
format for each ``date`` field.
75+
76+
.. code-block:: javascript
77+
78+
db.anniversaries.aggregate( [
79+
{
80+
$project: {
81+
yearNumber: { $isoWeekYear: "$date" }
82+
}
83+
}
84+
] )
85+
86+
The operation returns the following results:
87+
88+
.. code-block:: javascript
89+
90+
{ "_id" : 1, "yearNumber" : 2015 }
91+
{ "_id" : 2, "yearNumber" : 2016 }
92+
{ "_id" : 3, "yearNumber" : 2015 }
93+
{ "_id" : 4, "yearNumber" : 2014 }
94+
95+
.. seealso::
96+
97+
- :doc:`/reference/operator/aggregation/isoDayOfWeek`
98+
- :doc:`/reference/operator/aggregation/isoWeek`

0 commit comments

Comments
 (0)