- Reference >
- Operators >
- Query and Projection Operators >
- Projection Operators >
- $elemMatch (projection)
$elemMatch (projection)¶
See also
On this page
Definition¶
-
$elemMatch
¶ New in version 2.2.
The
$elemMatch
operator limits the contents of an<array>
field from the query results to contain only the first element matching the$elemMatch
condition.
Usage Considerations¶
Both the $
operator and the $elemMatch
operator project
a subset of elements from an array based on a condition.
The $
operator projects the array elements based on some condition
from the query statement.
The $elemMatch
projection operator takes an explicit condition
argument. This allows you to project based on a condition not in the query, or
if you need to project based on multiple fields in the array’s embedded documents.
See Array Field Limitations for an example.
Examples¶
The examples on the $elemMatch
projection operator
assumes a collection school
with the following documents:
Zipcode Search¶
The following find()
operation
queries for all documents where the value of the zipcode
field is 63109
. The $elemMatch
projection
returns only the first matching element of the students
array where the school
field has a value of 102
:
The operation returns the following documents:
- For the document with
_id
equal to1
, thestudents
array contains multiple elements with theschool
field equal to102
. However, the$elemMatch
projection returns only the first matching element from the array. - The document with
_id
equal to3
does not contain thestudents
field in the result since no element in itsstudents
array matched the$elemMatch
condition.
$elemMatch
with Multiple Fields¶
The $elemMatch
projection can specify criteria on multiple
fields:
The following find()
operation
queries for all documents where the value of the zipcode
field is 63109
. The projection includes the first
matching element of the students
array where the school
field has a value of 102
and the age
field is greater
than 10
:
The operation returns the three documents that have zipcode
equal to 63109
:
The document with _id
equal to 3
does not contain the students
field
since no array element matched the $elemMatch
criteria.
$elemMatch
with sort()
¶
When the find()
method includes a
sort()
, the find()
method
applies the sort()
to order the matching documents
before it applies the projection. This is a general rule when sorting
and projecting, and is discussed in Interaction with Projection.
If an array field contains multiple documents with the same field
name and the find()
method includes a
sort()
on that repeating field, the returned
documents may not reflect the sort order because the
sort()
was applied to the elements of the array
before the $elemMatch
projection.
An array’s sorting value is taken from either its “minimum” or “maximum” value,
depending on which way the sorting goes. The way that sort()
sorts documents containing arrays is described in Ascending/Descending Sort.
The following query includes a sort()
to order
by descending students.age
field:
The operation applies the sort()
to order the
documents that have the field zipcode
equal to 63109
and
then applies the projection. The operation returns the three
documents in the following order:
Even though the sort is descending, the younger student is listed first. This is because the sort occurred before the older students in Barney’s document were projected out.
See also
$ (projection)
operator