Skip to content

Commit f91c25a

Browse files
jocelyn-mendez1Jocelyn Mendez
jocelyn-mendez1
and
Jocelyn Mendez
authored
DOCSP-19866 $firstN & $lastN expressions (#155)
* DOCSP-19866 & expression * DOCSP-19866 & expression * DOCSP-19866 & expression * DOCSP-19866 updated aggregation operator page and release notes * DOCSP-19866 updated aggregation operator page and release notes * DOCSP-19866 added firstN & lastN * DOCSP-19866 corrected examples and behavior description * DOCSP-19866 corrected examples and behavior description * DOCSP-19866 numberLong correction Co-authored-by: Jocelyn Mendez <[email protected]>
1 parent 7adde2d commit f91c25a

File tree

5 files changed

+299
-0
lines changed

5 files changed

+299
-0
lines changed

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,10 @@ content: |
180180
* - :expression:`$first`
181181
182182
- Returns the first array element. Distinct from :group:`$first` accumulator.
183+
184+
* - :expression:`$firstN`
185+
186+
- Returns a specified number of elements from the beginning of an array.
183187
184188
* - :expression:`$in`
185189
@@ -200,6 +204,10 @@ content: |
200204
201205
- Returns the last array element. Distinct from :group:`$last` accumulator.
202206
207+
* - :expression:`$lastN`
208+
209+
- Returns a specified number of elements from the end of an array.
210+
203211
* - :expression:`$map`
204212
205213
- Applies a subexpression to each element of an array and

‎source/reference/operator/aggregation.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -502,6 +502,13 @@ Alphabetical Listing of Expression Operators
502502

503503
Distinct from the :group:`$first` accumulator.
504504

505+
* - :expression:`$firstN`
506+
507+
- Returns a specified number of elements from the beginning of an
508+
array.
509+
510+
.. versionadded:: 5.2
511+
505512
* - :expression:`$floor`
506513

507514
- Returns the largest integer less than or equal to the specified number.
@@ -633,7 +640,12 @@ Alphabetical Listing of Expression Operators
633640
.. versionadded:: 4.4
634641

635642
Distinct from the :group:`$last` accumulator.
643+
644+
* - :expression:`$lastN`
645+
646+
- Returns a specified number of elements from the end of an array.
636647

648+
.. versionadded:: 5.2
637649

638650
* - :expression:`$let`
639651

@@ -1232,6 +1244,7 @@ Alphabetical Listing of Expression Operators
12321244
/reference/operator/aggregation/expMovingAvg
12331245
/reference/operator/aggregation/filter
12341246
/reference/operator/aggregation/first
1247+
/reference/operator/aggregation/firstN
12351248
/reference/operator/aggregation/first-array-element
12361249
/reference/operator/aggregation/floor
12371250
/reference/operator/aggregation/function
@@ -1251,6 +1264,7 @@ Alphabetical Listing of Expression Operators
12511264
/reference/operator/aggregation/isoWeek
12521265
/reference/operator/aggregation/isoWeekYear
12531266
/reference/operator/aggregation/last
1267+
/reference/operator/aggregation/lastN
12541268
/reference/operator/aggregation/last-array-element
12551269
/reference/operator/aggregation/let
12561270
/reference/operator/aggregation/literal

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

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
========================
2+
$firstN (array operator)
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:: $firstN
17+
18+
.. versionadded:: 5.2
19+
20+
Returns a specified number of elements from the beginning of an
21+
array.
22+
23+
.. seealso::
24+
25+
- :expression:`$lastN`
26+
27+
- :expression:`$sortArray`
28+
29+
Syntax
30+
------
31+
32+
:expression:`$firstN` has the following syntax:
33+
34+
.. code-block:: javascript
35+
36+
{ $firstN: { n: <expression>, input: <expression> } }
37+
38+
.. list-table::
39+
:header-rows: 1
40+
:class: border-table
41+
42+
* - Field
43+
- Description
44+
45+
* - ``n``
46+
- An :ref:`expression <aggregation-expressions>` that resolves to a
47+
positive integer. The integer specifies the number of array elements
48+
that :expression:`$firstN` returns.
49+
50+
* - ``input``
51+
- An :ref:`expression <aggregation-expressions>` that resolves to the
52+
array from which to return ``n`` elements.
53+
54+
Behavior
55+
--------
56+
57+
- :expression:`$firstN` returns elements in the same order they appear in
58+
the input array.
59+
60+
- :expression:`$firstN` does not filter out ``null`` values in the input
61+
array.
62+
63+
- You cannot specify a value of ``n`` less than ``1``.
64+
65+
- If the specified ``n`` is greater than or equal to the number of elements
66+
in the ``input`` array, :expression:`$firstN` returns the ``input`` array.
67+
68+
- If ``input`` resolves to a non-array value, the aggregation operation
69+
errors.
70+
71+
Example
72+
-------
73+
74+
The collection ``games`` has the following documents:
75+
76+
.. code-block:: javascript
77+
:copyable: true
78+
79+
db.games.insertMany([
80+
{ "playerId" : 1, "score" : [ 1, 2, 3 ] },
81+
{ "playerId" : 2, "score" : [ 12, 90, 7, 89, 8 ] },
82+
{ "playerId" : 3, "score" : [ null ] },
83+
{ "playerId" : 4, "score" : [ ] },
84+
{ "playerId" : 5, "score" : [ 1293, null, 3489, 9 ]},
85+
{ "playerId" : 6, "score" : [ "12.1", 2, NumberLong("2090845886852"), 23 ]}
86+
])
87+
88+
The following example uses the :expression:`$firstN` operator to retrieve the
89+
first three scores for each player. The scores are returned in the new field
90+
``firstScores`` created by :pipeline:`$addFields`.
91+
92+
.. code-block:: javascript
93+
:copyable: true
94+
95+
db.games.aggregate([
96+
{ $addFields: { firstScores: { $firstN: { n: 3, 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, 29
104+
105+
[{
106+
"playerId": 1,
107+
"score": [ 1, 2, 3 ],
108+
"firstScores": [ 1, 2, 3 ]
109+
},
110+
{
111+
"playerId": 2,
112+
"score": [ 12, 90, 7, 89, 8 ],
113+
"firstScores": [ 12, 90, 7 ]
114+
},
115+
{
116+
"playerId": 3,
117+
"score": [ null ],
118+
"firstScores": [ null ]
119+
},
120+
{
121+
"playerId": 4,
122+
"score": [ ],
123+
"firstScores": [ ]
124+
},
125+
{
126+
"playerId": 5,
127+
"score": [ 1293, null, 3489, 9 ],
128+
"firstScores": [ 1293, null, 3489 ]
129+
},
130+
{
131+
"playerId": 6,
132+
"score": [ "12.1", 2, NumberLong("2090845886852"), 23 ],
133+
"firstScores": [ "12.1", 2, NumberLong("2090845886852") ]
134+
}]
135+

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

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
========================
2+
$lastN (array operator)
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:: $lastN
17+
18+
.. versionadded:: 5.2
19+
20+
Returns a specified number of elements from the end of an
21+
array.
22+
23+
.. seealso::
24+
25+
- :expression:`$firstN`
26+
27+
- :expression:`$sortArray`
28+
29+
Syntax
30+
------
31+
32+
:expression:`$lastN` has the following syntax:
33+
34+
.. code-block:: javascript
35+
36+
{ $lastN: { n: <expression>, input: <expression> } }
37+
38+
.. list-table::
39+
:header-rows: 1
40+
:class: border-table
41+
42+
* - Field
43+
- Description
44+
45+
* - ``n``
46+
- An :ref:`expression <aggregation-expressions>` that resolves to a
47+
positive integer. The integer specifies the number of array elements
48+
that :expression:`$lastN` returns.
49+
50+
* - ``input``
51+
- An :ref:`expression <aggregation-expressions>` that resolves to the
52+
array from which to return ``n`` elements.
53+
54+
Behavior
55+
--------
56+
57+
- :expression:`$lastN` returns elements in the same order they appear in
58+
the input array.
59+
60+
- :expression:`$lastN` does not filter out ``null`` values in the input
61+
array.
62+
63+
- You cannot specify a value of ``n`` less than ``1``.
64+
65+
- If the specified ``n`` is greater than or equal to the number of elements
66+
in the ``input`` array, :expression:`$lastN` returns the ``input`` array.
67+
68+
- If ``input`` resolves to a non-array value, the aggregation operation
69+
errors.
70+
71+
Example
72+
-------
73+
74+
The collection ``games`` has the following documents:
75+
76+
.. code-block:: javascript
77+
:copyable: true
78+
79+
db.games.insertMany([
80+
{ "playerId" : 1, "score" : [ 1, 2, 3 ] },
81+
{ "playerId" : 2, "score" : [ 12, 90, 7, 89, 8 ] },
82+
{ "playerId" : 3, "score" : [ null ] },
83+
{ "playerId" : 4, "score" : [ ] },
84+
{ "playerId" : 5, "score" : [ 1293, null, 3489, 9 ]},
85+
{ "playerId" : 6, "score" : [ "12.1", 2, NumberLong("2090845886852"), 23 ]}
86+
])
87+
88+
The following example uses the :expression:`$lastN` operator to retrieve the
89+
last three scores for each player. The scores are returned in the new field
90+
``lastScores`` created by :pipeline:`$addFields`.
91+
92+
.. code-block:: javascript
93+
:copyable: true
94+
95+
db.games.aggregate([
96+
{ $addFields: { lastScores: { $lastN: { n: 3, 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, 29
104+
105+
[{
106+
"playerId": 1,
107+
"score": [ 1, 2, 3 ],
108+
"lastScores": [ 1, 2, 3 ]
109+
},
110+
{
111+
"playerId": 2,
112+
"score": [ 12, 90, 7, 89, 8 ],
113+
"lastScores": [ 7, 89, 8 ]
114+
},
115+
{
116+
"playerId": 3,
117+
"score": [ null ],
118+
"lastScores": [ null ]
119+
},
120+
{
121+
"playerId": 4,
122+
"score": [ ],
123+
"lastScores": [ ]
124+
},
125+
{
126+
"playerId": 5,
127+
"score": [ 1293, null, 3489, 9 ],
128+
"lastScores": [ null, 3489, 9 ]
129+
},
130+
{
131+
"playerId": 6,
132+
"score": [ "12.1", 2, NumberLong("2090845886852"), 23 ],
133+
"lastScores": [ 2, NumberLong("2090845886852"), 23 ]
134+
}]

‎source/release-notes/5.2.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,14 @@ MongoDB 5.2 introduces the following aggregation operators:
3535
- Returns an aggregation of the bottom ``n`` elements within a group,
3636
according to the specified sort order.
3737

38+
* - :expression:`$firstN`
39+
- Returns a specified number of elements from the beginning of an
40+
array.
41+
42+
* - :expression:`$lastN`
43+
- Returns a specified number of elements from the end of an
44+
array.
45+
3846
* - :group:`$locf`
3947
- .. include:: /includes/fact-locf-description.rst
4048

0 commit comments

Comments
 (0)