Docs Home → MongoDB Manual

$elemMatch (projection)

On this page本页内容

Tip

See also: 另请参阅：

$elemMatch (query)（查询）

Definition定义

$elemMatch

The $elemMatch operator limits the contents of an <array> field from the query results to contain only the first element matching the $elemMatch condition.$elemMatch运算符将查询结果中<array>字段的内容限制为仅包含与$elemMatch条件匹配的第一个元素。

Usage Considerations使用注意事项

Returned Element返回的元素

Both the $ operator and the $elemMatch operator project the first matching element from an array based on a condition.$运算符和$elemMatch运算符都根据条件从数组中投影第一个匹配元素。

The $ operator projects the first matching array element from each document in a collection based on some condition from the query statement.$运算符根据查询语句中的某个条件，从集合中的每个文档中投影第一个匹配的数组元素。

The $elemMatch projection operator takes an explicit condition argument. $elemMatch投影运算符采用显式条件参数。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.有关示例，请参阅数组字段限制。

Field Order字段顺序

Starting in MongoDB 4.4, regardless of the ordering of the fields in the document, the $elemMatch projection of an existing field returns the field after the other existing field inclusions.从MongoDB 4.4开始，无论文档中字段的顺序如何，现有字段的$elemMatch投影都会在其他现有字段包含之后返回该字段。

For example, consider a players collection with the following document:例如，考虑一个带有以下文档的players集合：

db.players.insertOne( {
   name: "player1",
   games: [ { game: "abc", score: 8 }, { game: "xyz", score: 5 } ],
   joined: new Date("2020-01-01"),
   lastLogin: new Date("2020-05-01")
} )

In version 4.4+, the following projection returns the games field after the other existing fields included in the projection even though in the document, the field is listed before joined and lastLogin fields:在4.4+版本中，以下投影会在投影中包含的其他现有字段之后返回games字段，即使在文档中，该字段列在joind和lastLogin字段之前：

db.players.find( {}, { games: { $elemMatch: { score: { $gt: 5 } } }, joined: 1, lastLogin: 1 } )

That is, the operation returns the following document:也就是说，该操作返回以下文档：

{
   "_id" : ObjectId("5edef64a1c099fff6b033977"),
   "joined" : ISODate("2020-01-01T00:00:00Z"),
   "lastLogin" : ISODate("2020-05-01T00:00:00Z"),
   "games" : [ { "game" : "abc", "score" : 8 } ]
}

In version 4.2 and earlier, the $elemMatch projection of an existing field upholds the ordering in the document:在4.2及更早版本中，现有字段的$elemMatch投影支持文档中的顺序：

{
  "_id" : ObjectId("5edef91e76ddff7d92f118e1"),
  "games" : [ { "game" : "abc", "score" : 8 } ],
  "joined" : ISODate("2020-01-01T00:00:00Z"),
  "lastLogin" : ISODate("2020-05-01T00:00:00Z")
}

Restrictions限制

Examples实例

The examples on the $elemMatch projection operator assumes a collection schools with the following documents:$elemMatch投影运算符上的示例假定集合schools具有以下文档：

{
 _id: 1,
 zipcode: "63109",
 students: [
              { name: "john", school: 102, age: 10 },
              { name: "jess", school: 102, age: 11 },
              { name: "jeff", school: 108, age: 15 }
           ]
}
{
 _id: 2,
 zipcode: "63110",
 students: [
              { name: "ajax", school: 100, age: 7 },
              { name: "achilles", school: 100, age: 8 },
           ]
}
{
 _id: 3,
 zipcode: "63109",
 students: [
              { name: "ajax", school: 100, age: 7 },
              { name: "achilles", school: 100, age: 8 },
           ]
}
{
 _id: 4,
 zipcode: "63109",
 students: [
              { name: "barney", school: 102, age: 7 },
              { name: "ruth", school: 102, age: 16 },
           ]
}

Zipcode SearchZipcode搜索

The following find() operation queries for all documents where the value of the zipcode field is 63109. 下面的find()操作查询zipcode字段值为63109的所有文档。The $elemMatch projection returns only the first matching element of the students array where the school field has a value of 102:$elemMatch投影仅返回students数组的第一个匹配元素，其中school字段的值为102：

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

The operation returns the following documents that have zipcode equal to 63109 and projects the students array using $elemMatch:该操作返回以下zipcode等于63109的文档，并使用$elemMatch投影students数组：

{ "_id" : 1, "students" : [ { "name" : "john", "school" : 102, "age" : 10 } ] }
{ "_id" : 3 }
{ "_id" : 4, "students" : [ { "name" : "barney", "school" : 102, "age" : 7 } ] }
  • For the document with _id equal to 1, the students array contains multiple elements with the school field equal to 102. However, the $elemMatch projection returns only the first matching element from the array.对于_id等于1的文档，students数组包含school字段等于102的多个元素。但是，$elemMatch投影只返回数组中的第一个匹配元素。
  • The document with _id equal to 3 does not contain the students field in the result since no element in its students array matched the $elemMatch condition._id等于3的文档在结果中不包含students字段，因为其students数组中没有任何元素与$elemMatch条件匹配。

$elemMatch with Multiple Fields具有多个字段

The $elemMatch projection can specify criteria on multiple fields:$elemMatch投影可以在多个字段上指定条件：

The following find() operation queries for all documents where the value of the zipcode field is 63109. 下面的find()操作查询zipcode字段值为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:投影包括students数组的第一个匹配元素，其中school字段的值为102并且age字段大于10：

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

The operation returns the three documents that have zipcode equal to 63109:该操作返回zipcode等于63109的三个文档：

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

The document with _id equal to 3 does not contain the students field since no array element matched the $elemMatch criteria._id等于3的文档不包含students字段，因为没有数组元素与$elemMatch条件匹配。

Tip

See also: 另请参阅：

$ (projection)（投影） operator运算符