$elemMatch (projection)

See also

$elemMatch (query)

Definition

  • $elemMatch
  • The $elemMatch operator limits the contents of an<array> field from the query results to contain only the firstelement matching the $elemMatch condition.

Usage Considerations

Both the $ operator and the $elemMatch operator projectthe first matching element from an array based on a condition.

The $ operator projects the first matching array element from eachdocument in a collection based on some condition from the query statement.

The $elemMatch projection operator takes an explicit conditionargument. This allows you to project based on a condition not in the query, orif you need to project based on multiple fields in the array’s embedded documents.See Array Field Limitations for an example.

db.collection.find() operations on views do not support $elemMatch projection operator.

Examples

The examples on the $elemMatch projection operatorassumes a collection schools with the following documents:

  1. {
  2.  _id: 1,
  3.  zipcode: "63109",
  4.  students: [
  5.               { name: "john", school: 102, age: 10 },
  6.               { name: "jess", school: 102, age: 11 },
  7.               { name: "jeff", school: 108, age: 15 }
  8.            ]
  9. }
  10. {
  11.  _id: 2,
  12.  zipcode: "63110",
  13.  students: [
  14.               { name: "ajax", school: 100, age: 7 },
  15.               { name: "achilles", school: 100, age: 8 },
  16.            ]
  17. }
  18. {
  19.  _id: 3,
  20.  zipcode: "63109",
  21.  students: [
  22.               { name: "ajax", school: 100, age: 7 },
  23.               { name: "achilles", school: 100, age: 8 },
  24.            ]
  25. }
  26. {
  27.  _id: 4,
  28.  zipcode: "63109",
  29.  students: [
  30.               { name: "barney", school: 102, age: 7 },
  31.               { name: "ruth", school: 102, age: 16 },
  32.            ]
  33. }

The following find() operationqueries for all documents where the value of the zipcodefield is 63109. The $elemMatch projectionreturns only the first matching element of the studentsarray where the school field has a value of 102:

  1. db.schools.find( { zipcode: "63109" },
  2.                  { students: { $elemMatch: { school: 102 } } } )

The operation returns the following documents that have zipcodeequal to 63109 and projects the students array using$elemMatch:

  1. { "_id" : 1, "students" : [ { "name" : "john", "school" : 102, "age" : 10 } ] }
  2. { "_id" : 3 }
  3. { "_id" : 4, "students" : [ { "name" : "barney", "school" : 102, "age" : 7 } ] }
  • For the document with _id equal to 1, the studentsarray contains multiple elements with the school fieldequal to 102. However, the $elemMatchprojection returns only the first matching element from thearray.
  • The document with _id equal to 3 does not contain thestudents field in the result since no element in itsstudents array matched the $elemMatchcondition.

$elemMatch with Multiple Fields

The $elemMatch projection can specify criteria on multiplefields:

The following find() operationqueries for all documents where the value of the zipcodefield is 63109. The projection includes the firstmatching element of the students array where the schoolfield has a value of 102 and the age field is greaterthan 10:

  1. db.schools.find( { zipcode: "63109" },
  2.                  { students: { $elemMatch: { school: 102, age: { $gt: 10} } } } )

The operation returns the three documents that have zipcode equal to 63109:

  1. { "_id" : 1, "students" : [ { "name" : "jess", "school" : 102, "age" : 11 } ] }
  2. { "_id" : 3 }
  3. { "_id" : 4, "students" : [ { "name" : "ruth", "school" : 102, "age" : 16 } ] }

The document with _id equal to 3 does not contain the students fieldsince no array element matched the $elemMatch criteria.

See also

$ (projection) operator