Skip to content

Commit b4d6c22

Browse files
jocelyn-mendez1Jocelyn Mendez
authored and
jeff-allen-mongo
committed
DOCSP-19867 $minN & maxN expressions (#138)
* DOCSP-19867 & expressions * DOCSP-19867 & expressions * DOCSP-19867 & expressions * DOCSP-19867 & expressions * DOCSP-19867 & expressions * DOCSP-19867 first set of updates to pages * DOCSP-19867 first set of updates to pages * DOCSP-19867 added & to release notes & to list of agg array operators * DOCSP-19867 added to alphabetical list of operators * DOCSP-19867 changes to behavioral description * DOCSP-19867 changes to behavioral description * DOCSP-19867 changes to behavioral description * DOCSP-19867 updated definitions of expressions * DOCSP-19867 removing behavior bullet * DOCP-19867 corrected to versionadded Co-authored-by: Jocelyn Mendez <[email protected]>
1 parent b712883 commit b4d6c22

File tree

5 files changed

+286
-0
lines changed

5 files changed

+286
-0
lines changed

‎source/includes/extracts-agg-operators.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,14 @@ content: |
214214
returns the array of resulting values in order. Accepts named
215215
parameters.
216216
217+
* - :expression:`$maxN`
218+
219+
- Returns the ``n`` largest values in an array.
220+
221+
* - :expression:`$minN`
222+
223+
- Returns the ``n`` smallest values in an array.
224+
217225
* - :expression:`$objectToArray`
218226
219227
- Converts a document to an array of documents representing

‎source/reference/operator/aggregation.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -721,6 +721,12 @@ Alphabetical Listing of Expression Operators
721721
.. versionchanged:: 5.0
722722

723723
Available in :pipeline:`$setWindowFields` stage.
724+
725+
* - :expression:`$maxN`
726+
727+
- Returns the ``n`` largest values in an array.
728+
729+
.. versionadded:: 5.2
724730

725731

726732
* - :expression:`$mergeObjects`
@@ -741,6 +747,12 @@ Alphabetical Listing of Expression Operators
741747
.. versionchanged:: 5.0
742748

743749
Available in :pipeline:`$setWindowFields` stage.
750+
751+
* - :expression:`$minN`
752+
753+
- Returns the ``n`` smallest values in an array.
754+
755+
.. versionadded:: 5.2
744756

745757

746758
* - :expression:`$millisecond`
@@ -1298,9 +1310,11 @@ Alphabetical Listing of Expression Operators
12981310
/reference/operator/aggregation/ltrim
12991311
/reference/operator/aggregation/map
13001312
/reference/operator/aggregation/max
1313+
/reference/operator/aggregation/maxN
13011314
/reference/operator/aggregation/mergeObjects
13021315
/reference/operator/aggregation/meta
13031316
/reference/operator/aggregation/min
1317+
/reference/operator/aggregation/minN
13041318
/reference/operator/aggregation/millisecond
13051319
/reference/operator/aggregation/minute
13061320
/reference/operator/aggregation/mod

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

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
.. _maxN:
2+
3+
======================
4+
$maxN (array operator)
5+
======================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. expression:: $maxN
19+
20+
.. versionadded:: 5.2
21+
22+
Returns the ``n`` largest values in an array.
23+
24+
.. seealso::
25+
26+
:expression:`$minN`
27+
28+
Syntax
29+
------
30+
31+
:expression:`$maxN` has the following syntax:
32+
33+
.. code-block:: javascript
34+
35+
{ $maxN: { n: <expression>, input: <expression> } }
36+
37+
.. list-table::
38+
:header-rows: 1
39+
:class: border-table
40+
41+
* - Field
42+
- Description
43+
44+
* - ``n``
45+
- An :ref:`expression <aggregation-expressions>` that resolves to a
46+
positive integer. The integer specifies the number of array elements
47+
that :expression:`$maxN` returns.
48+
49+
* - ``input``
50+
- An :ref:`expression <aggregation-expressions>` that resolves to the
51+
array from which to return the maximal ``n`` elements.
52+
53+
Behavior
54+
--------
55+
56+
- You cannot specify a value of ``n`` less than ``1``.
57+
58+
- :expression:`$maxN` filters out ``null`` values found in the ``input``
59+
array.
60+
61+
- If the specified ``n`` is greater than or equal to the number of elements
62+
in the ``input`` array, :expression:`$maxN` returns all elements in the
63+
``input`` array.
64+
65+
- If ``input`` resolves to a non-array value, the aggregation
66+
operation errors.
67+
68+
- If ``input`` contains both numeric and string elements, the string elements
69+
are sorted before numeric elements according to the
70+
:ref:`BSON comparison order <bson-types-comparison-order>`.
71+
72+
Example
73+
-------
74+
75+
Create a ``scores`` collection with the following documents:
76+
77+
.. code-block:: javascript
78+
:copyable: true
79+
80+
db.scores.insertMany([
81+
{ "playerId" : 1, "score" : [ 1, 2, 3 ] },
82+
{ "playerId" : 2, "score" : [ 12, 90, 7, 89, 8 ] },
83+
{ "playerId" : 3, "score" : [ null ] },
84+
{ "playerId" : 4, "score" : [ ] }
85+
{ "playerId" : 5, "score" : [ 1293, "2", 3489, 9 ]}
86+
])
87+
88+
The following example uses the :expression:`$maxN` operator to retrieve the two
89+
highest scores for each player. The highest scores are returned in the new field
90+
``maxScores`` created by :pipeline:`$addFields`.
91+
92+
.. code-block:: javascript
93+
:copyable: true
94+
95+
db.scores.aggregate([
96+
{ $addFields: { maxScores: { $maxN: { n: 2, input: "$score" } } } }
97+
])
98+
99+
The operation returns the following results:
100+
101+
.. code-block:: javascript
102+
:copyable: true
103+
:emphasize-lines: 4, 9, 14, 19, 24
104+
105+
[{
106+
"playerId": 1,
107+
"score": [ 1, 2, 3 ],
108+
"maxScores": [ 3, 2 ]
109+
},
110+
{
111+
"playerId": 2,
112+
"score": [ 12, 90, 7, 89, 8 ],
113+
"maxScores": [ 90, 89 ]
114+
},
115+
{
116+
"playerId": 3,
117+
"score": [ null ],
118+
"maxScores": [ ]
119+
},
120+
{
121+
"playerId": 4,
122+
"score": [ ],
123+
"maxScores": [ ]
124+
},
125+
{
126+
"playerId": 5,
127+
"score": [ 1293, "2", 3489, 9 ],
128+
"maxScores": [ "2", 3489 ]
129+
}]

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

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
.. _minN:
2+
3+
======================
4+
$minN (array operator)
5+
======================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. expression:: $minN
19+
20+
.. versionadded:: 5.2
21+
22+
Returns the ``n`` smallest values in an array.
23+
24+
.. seealso::
25+
26+
:expression:`$maxN`
27+
28+
Syntax
29+
------
30+
31+
:expression:`$minN` has the following syntax:
32+
33+
.. code-block:: javascript
34+
35+
{ $minN: { n: <expression>, input: <expression> } }
36+
37+
.. list-table::
38+
:header-rows: 1
39+
:class: border-table
40+
41+
* - Field
42+
- Description
43+
44+
* - ``n``
45+
- An :ref:`expression <aggregation-expressions>` that resolves to a
46+
positive integer. The integer specifies the number of array elements
47+
that :expression:`$minN` returns.
48+
49+
* - ``input``
50+
- An :ref:`expression <aggregation-expressions>` that resolves to the
51+
array from which to return the minimal ``n`` elements.
52+
53+
Behavior
54+
--------
55+
56+
- You cannot specify a value of ``n`` less than ``1``.
57+
58+
- :expression:`$minN` filters out ``null`` values found in the ``input``
59+
array.
60+
61+
- If the specified ``n`` is greater than or equal to the number of elements
62+
in the ``input`` array, :expression:`$minN` returns all elements in the
63+
``input`` array.
64+
65+
- If ``input`` resolves to a non-array value, the aggregation
66+
operation errors.
67+
68+
- If ``input`` contains both numeric and string elements, the numeric elements
69+
are sorted before string elements according to the
70+
:ref:`BSON comparison order <bson-types-comparison-order>`.
71+
72+
Example
73+
-------
74+
75+
Create a ``scores`` collection with the following documents:
76+
77+
.. code-block:: javascript
78+
:copyable: true
79+
80+
db.scores.insertMany([
81+
{ "playerId" : 1, "score" : [ 1, 2, 3 ] },
82+
{ "playerId" : 2, "score" : [ 12, 90, 7, 89, 8 ] },
83+
{ "playerId" : 3, "score" : [ null ] },
84+
{ "playerId" : 4, "score" : [ ] },
85+
{ "playerId" : 5, "score" : [ 1293, "2", 3489, 9 ]}
86+
])
87+
88+
The following example uses the :expression:`$minN` operator to retrieve the two
89+
lowest scores for each player. The lowest scores are returned in the new field
90+
``minScores`` created by :pipeline:`$addFields`.
91+
92+
.. code-block:: javascript
93+
:copyable: true
94+
95+
db.scores.aggregate([
96+
{ $addFields: { minScores: { $minN: { n: 2, input: "$score" } } } }
97+
])
98+
99+
The operation returns the following results:
100+
101+
.. code-block:: javascript
102+
:copyable: true
103+
:emphasize-lines: 4, 9, 14, 19, 24
104+
105+
[{
106+
"playerId": 1,
107+
"score": [ 1, 2, 3 ],
108+
"minScores": [ 1, 2 ]
109+
},
110+
{
111+
"playerId": 2,
112+
"score": [ 12, 90, 7, 89, 8 ],
113+
"minScores": [ 7, 8 ]
114+
},
115+
{
116+
"playerId": 3,
117+
"score": [ null ],
118+
"minScores": [ ]
119+
},
120+
{
121+
"playerId": 4,
122+
"score": [ ],
123+
"minScores": [ ]
124+
},
125+
{
126+
"playerId": 5,
127+
"score": [ 1293, "2", 3489, 9 ],
128+
"minScores": [ 9, 1293 ]
129+
}]

‎source/release-notes/5.2.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,12 @@ MongoDB 5.2 introduces the following aggregation operators:
5050
* - :group:`$locf`
5151
- .. include:: /includes/fact-locf-description.rst
5252

53+
* - :expression:`$maxN`
54+
- Returns the ``n`` largest values in an array.
55+
56+
* - :expression:`$minN`
57+
- Returns the ``n`` smallest values in an array.
58+
5359
* - :group:`$top`
5460
- Returns the top element within a group according to the specified
5561
sort order.

0 commit comments

Comments
 (0)