In 5.1 and below, $filter returns all matching array elements of its input. The new feature implemented in this ticket, allows the user to add a "limit" option to the $filter expression to restrict the number of matches returned.

User-Facing Syntax

{ $filter:

}

The new syntax introduces an optional field, limit, that accepts any number expression. The limit must be a positive integer greater than zero. A limit of zero or less is rejected, as is a limit that is not an integer (e.g. NumberDouble(3.14) or the string "3"). However, integer values of non-integer types (e.g. 3.000) are supported to match the behavior of $limit. Other existing validation rules still apply: input and cond are always required, and as can be optionally specified.

To be consistent with $limit, for a limit of k, the $filter operation returns the first k elements in the order in which they appeared in the input array. If the array has fewer than k matching elements, the operation returns < k matches in order.