Skip to content

Commit cf798ff

Browse files
jocelyn-mendez1Jocelyn Mendez
jocelyn-mendez1
and
Jocelyn Mendez
authored
DOCS-14896 $filter operator new limit field (#445)
* DOCS-14896 new field limit * DOCS-14896 added release notes * DOCS-14896 two additional limit examples * DOCS-14896 two additional limit examples * DOCSP-14896 fixing //optional line up * DOCSP-14896 fixing //optional line up * DOCSP-14896 fixing //optional line up * DOCSP-14896 fixing //optional line up * DOCS-14896 added new behavioral example * DOCS-14896 added new behavioral example * DOCS-14896 limit definition Co-authored-by: Jocelyn Mendez <[email protected]>
1 parent d883adb commit cf798ff

File tree

2 files changed

+241
-33
lines changed

2 files changed

+241
-33
lines changed

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

Lines changed: 234 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,15 @@ Definition
2525

2626
.. code-block:: javascript
2727

28-
{ $filter: { input: <array>, as: <string>, cond: <expression> } }
28+
{
29+
$filter:
30+
{
31+
input: <array>,
32+
cond: <expression>,
33+
as: <string>,
34+
limit: <number expression>
35+
}
36+
}
2937

3038
.. list-table::
3139
:header-rows: 1
@@ -39,13 +47,6 @@ Definition
3947
- An :ref:`expression <aggregation-expressions>` that
4048
resolves to an array.
4149

42-
* - ``as``
43-
44-
- Optional. A name for the :doc:`variable
45-
</reference/aggregation-variables>` that represents each
46-
individual element of the ``input`` array. If no name is
47-
specified, the variable name defaults to ``this``.
48-
4950
* - ``cond``
5051

5152
- An :ref:`expression <aggregation-expressions>` that resolves
@@ -54,6 +55,24 @@ Definition
5455
element of the ``input`` array individually with the variable
5556
name specified in ``as``.
5657

58+
* - ``as``
59+
60+
- Optional. A name for the :doc:`variable
61+
</reference/aggregation-variables>` that represents each
62+
individual element of the ``input`` array. If no name is
63+
specified, the variable name defaults to ``this``.
64+
65+
* - ``limit``
66+
- Optional. A number expression that restricts the number of matching
67+
array elements that :expression:`$filter` returns. You cannot
68+
specify a limit less than ``1``. The matching array elements are
69+
returned in the order they appear in the input array.
70+
71+
If the specified ``limit`` is greater than the number of matching
72+
array elements, :expression:`$filter` returns all matching array
73+
elements. If the limit is ``null``, :expression:`$filter` returns
74+
all matching array elements.
75+
5776
For more information on expressions, see
5877
:ref:`aggregation-expressions`.
5978

@@ -83,41 +102,79 @@ Behavior
83102

84103
- ``[ 1, 2, 3.1, NumberLong(4) ]``
85104

86-
Example
87-
-------
105+
* - .. code-block:: javascript
106+
:copyable: false
107+
:emphasize-lines: 9
108+
109+
{
110+
$filter: {
111+
input: [ 1, "a", 2, null, 3.1, NumberLong(4), "5" ],
112+
as: "num",
113+
cond: { $and:[
114+
{ $gte: [ "$$num", NumberLong("-9223372036854775807") ] },
115+
{ $gte: [ "$$num", NumberLong("9223372036854775807") ] }
116+
] }
117+
limit: 2
118+
}
119+
}
120+
121+
- ``[ 1, 2 ]``
122+
123+
* - .. code-block:: javascript
124+
:copyable: false
125+
:emphasize-lines: 9
126+
127+
{
128+
$filter: {
129+
input: [ 1, "a", 2, null, 3.1, NumberLong(4), "5" ],
130+
as: "num",
131+
cond: { $and:[
132+
{ $gte: [ "$$num", NumberLong("-9223372036854775807") ] },
133+
{ $gte: [ "$$num", NumberLong("9223372036854775807") ] }
134+
] }
135+
limit: { $add: [ 0, 1 ]}
136+
}
137+
}
138+
139+
- ``[ 1 ]``
140+
141+
Examples
142+
--------
88143

89144
A collection ``sales`` has the following documents:
90145

91146
.. code-block:: javascript
92147

93-
{
94-
_id: 0,
95-
items: [
96-
{ item_id: 43, quantity: 2, price: 10 },
97-
{ item_id: 2, quantity: 1, price: 240 }
98-
]
99-
}
100-
{
101-
_id: 1,
102-
items: [
103-
{ item_id: 23, quantity: 3, price: 110 },
104-
{ item_id: 103, quantity: 4, price: 5 },
105-
{ item_id: 38, quantity: 1, price: 300 }
106-
]
107-
}
108-
{
109-
_id: 2,
110-
items: [
111-
{ item_id: 4, quantity: 1, price: 23 }
112-
]
113-
}
148+
db.sales.insertMany( [
149+
{
150+
_id: 0,
151+
items: [
152+
{ item_id: 43, quantity: 2, price: 10 },
153+
{ item_id: 2, quantity: 1, price: 240 }
154+
]
155+
},
156+
{
157+
_id: 1,
158+
items: [
159+
{ item_id: 23, quantity: 3, price: 110 },
160+
{ item_id: 103, quantity: 4, price: 5 },
161+
{ item_id: 38, quantity: 1, price: 300 }
162+
]
163+
},
164+
{
165+
_id: 2,
166+
items: [
167+
{ item_id: 4, quantity: 1, price: 23 }
168+
]
169+
}
170+
] )
114171

115172
The following example filters the ``items`` array to only include
116173
documents that have a ``price`` greater than or equal to ``100``:
117174

118175
.. code-block:: javascript
119176

120-
db.sales.aggregate([
177+
db.sales.aggregate( [
121178
{
122179
$project: {
123180
items: {
@@ -129,7 +186,7 @@ documents that have a ``price`` greater than or equal to ``100``:
129186
}
130187
}
131188
}
132-
])
189+
] )
133190

134191
The operation produces the following results:
135192

@@ -149,3 +206,147 @@ The operation produces the following results:
149206
]
150207
}
151208
{ "_id" : 2, "items" : [ ] }
209+
210+
Using the ``limit`` field
211+
~~~~~~~~~~~~~~~~~~~~~~~~~
212+
213+
This example uses the ``sales`` collection from the previous example.
214+
215+
The example uses the ``limit`` field to specifiy the number of matching elements
216+
returned in each ``items`` array.
217+
218+
.. code-block:: javascript
219+
:emphasize-lines: 9
220+
221+
db.sales.aggregate( [
222+
{
223+
$project: {
224+
items: {
225+
$filter: {
226+
input: "$items",
227+
cond: { $gte: [ "$$item.price", 100 ] },
228+
as: "item",
229+
limit: 1
230+
}
231+
}
232+
}
233+
}
234+
] )
235+
236+
The operation produces the following results:
237+
238+
.. code-block:: javascript
239+
240+
{
241+
"_id" : 0,
242+
"items" : [
243+
{ "item_id" : 2, "quantity" : 1, "price" : 240 }
244+
]
245+
}
246+
{
247+
"_id" : 1,
248+
"items" : [
249+
{ "item_id" : 23, "quantity" : 3, "price" : 110 }
250+
]
251+
}
252+
{ "_id" : 2, "items" : [ ] }
253+
254+
``limit`` as a Numeric Expression
255+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
256+
257+
This example uses the ``sales`` collection from the previous example.
258+
259+
The following example uses a numeric expression for the ``limit`` field to
260+
specifiy the number of matching elements returned in each ``items`` array.
261+
262+
.. code-block:: javascript
263+
:emphasize-lines: 9
264+
265+
db.sales.aggregate( [
266+
{
267+
$project: {
268+
items: {
269+
$filter: {
270+
input: "$items",
271+
cond: { $lte: [ "$$item.price", 150] },
272+
as: "item",
273+
limit: 2.000
274+
}
275+
}
276+
}
277+
}
278+
] )
279+
280+
The operation produces the following results:
281+
282+
.. code-block:: javascript
283+
284+
{
285+
"_id": 0,
286+
"items": [
287+
{ "item_id": 43, "quantity": 2, "price": 10 }
288+
]
289+
},
290+
{
291+
"_id": 1,
292+
"items": [
293+
{ "item_id": 23, "quantity": 3, "price": 110 },
294+
{ "item_id": 103, "quantity": 4, "price": 5 }
295+
]
296+
},
297+
{
298+
"_id": 2,
299+
"items": [
300+
{ "item_id": 4, "quantity": 1, "price": 23 }
301+
]
302+
}
303+
304+
``limit`` Greater than Possible Matches
305+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
306+
307+
This example uses the ``sales`` collection from the previous example.
308+
309+
The example uses a ``limit`` field value that is larger than the possible
310+
number of matching elements that can be returned.
311+
312+
.. code-block:: javascript
313+
:emphasize-lines: 9
314+
315+
db.sales.aggregate( [
316+
{
317+
$project: {
318+
items: {
319+
$filter: {
320+
input: "$items",
321+
cond: { $gte: [ "$$item.price", 100] },
322+
as: "item",
323+
limit: 5
324+
}
325+
}
326+
}
327+
}
328+
] )
329+
330+
The operation produces the following results:
331+
332+
.. code-block:: javascript
333+
334+
[
335+
{
336+
"_id": 0,
337+
"items": [
338+
{ "item_id": 2, "quantity": 1, "price": 240 }
339+
]
340+
},
341+
{
342+
"_id": 1,
343+
"items": [
344+
{ "item_id": 23, "quantity": 3, "price": 110 },
345+
{ "item_id": 38, "quantity": 1, "price": 300 }
346+
]
347+
},
348+
{
349+
"_id": 2,
350+
"items": []
351+
}
352+
]

‎source/release-notes/5.2.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,13 @@ MongoDB 5.2 introduces the following aggregation operators:
9595
General Aggregation Improvements
9696
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9797

98+
:expression:`$filter` Operator's ``limit`` Field
99+
````````````````````````````````````````````````
100+
101+
Starting in MongoDB 5.2, the :expression:`$filter` operator includes the
102+
optional ``limit`` field. The ``limit`` field restricts the number of
103+
matching array elements that the :expression:`$filter` operator returns.
104+
98105
:expression:`$convert` Supports Timestamp Conversion to Date
99106
````````````````````````````````````````````````````````````
100107

0 commit comments

Comments
 (0)