Database Manual / Reference / Query Language / Query Predicates / Arrays

$elemMatch (query)

Tip

$elemMatch (projection)

Definition定义

$elemMatch

The $elemMatch operator matches documents that contain an array field with at least one element that matches all the specified query criteria.$elemMatch运算符将包含数组字段的文档与至少一个与所有指定查询条件匹配的元素进行匹配。

Compatibility兼容性

You can use $elemMatch for deployments hosted in the following environments:您可以将$elemMatch用于在以下环境中托管的部署：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务
  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

{ <field>: { $elemMatch: { <query1>, <query2>, ... } } }

Behavior行为

Examples示例

Element Match元素匹配

Given the following documents in the scores collection:鉴于scores集合中的以下文件：

{ _id: 1, results: [ 82, 85, 88 ] }
{ _id: 2, results: [ 75, 88, 89 ] }

The following query matches only those documents where the results array contains at least one element that is both greater than or equal to 80 and is less than 85:以下查询仅匹配results数组中至少包含一个大于或等于80且小于85的元素的文档：

db.scores.find(
   { results: { $elemMatch: { $gte: 80, $lt: 85 } } }
)

The query returns the following document because the element 82 is both greater than or equal to 80 and is less than 85:查询返回以下文档，因为元素82既大于或等于80又小于85：

{ "_id" : 1, "results" : [ 82, 85, 88 ] }

For more information on specifying multiple criteria on array elements, see Specify Multiple Conditions for Array Elements.有关为数组元素指定多个条件的详细信息，请参阅为数组元素设置多个条件。

Array of Embedded Documents嵌入式文档数组

This statement inserts documents into the survey collection:此声明将文档插入到survey集合中：

db.survey.insertMany( [
   { "_id": 1, "results": [ { "product": "abc", "score": 10 },
                            { "product": "xyz", "score": 5 } ] },
   { "_id": 2, "results": [ { "product": "abc", "score": 8 },
                            { "product": "xyz", "score": 7 } ] },
   { "_id": 3, "results": [ { "product": "abc", "score": 7 },
                            { "product": "xyz", "score": 8 } ] },
   { "_id": 4, "results": [ { "product": "abc", "score": 7 },
                            { "product": "def", "score": 8 } ] },
   { "_id": 5, "results": { "product": "xyz", "score": 7 } }
] )

The document with an _id of 5 doesn't contain an array. That document is included to show that $elemMatch only matches array elements, which you will see in the following examples._id为5的文档不包含数组。包含该文档是为了表明$elemMatch只匹配数组元素，您将在以下示例中看到。

The following query matches documents where results contains at least one element where product is "xyz" and score is greater than or equal to 8:以下查询匹配results至少包含一个元素的文档，其中product为"xyz"且score大于或等于8：

db.survey.find(
   { results: { $elemMatch: { product: "xyz", score: { $gte: 8 } } } }
)

Specifically, the query matches the following document:具体来说，查询匹配以下文档：

{ "_id" : 3, "results" : [ { "product" : "abc", "score" : 7 },
                           { "product" : "xyz", "score" : 8 } ] }

Single Query Condition单一查询条件

The following sections show the output differences when you use $elemMatch with a single query condition, and omit $elemMatch.以下部分显示了将$elemMatch与单个查询条件一起使用并省略$elemMack时的输出差异。

Example 1示例1

Query with $elemMatch:使用$elemMatch进行查询：

db.survey.find(
   { results: { $elemMatch: { product: "xyz" } } }
)

The query returns documents where any product in results is "xyz":查询返回的文档中，results中的任何product都是"xyz"：

[
   {
      _id: 1,
      results: [ { product: 'abc', score: 10 }, { product: 'xyz', score: 5 } ]
   },
   {
      _id: 2,
      results: [ { product: 'abc', score: 8 }, { product: 'xyz', score: 7 } ]
   },
   {
      _id: 3,
      results: [ { product: 'abc', score: 7 }, { product: 'xyz', score: 8 } ]
   }
]

Query without $elemMatch:不用$elemMatch的查询：

db.survey.find(
   { "results.product": "xyz" }
)

In the following output, notice that the document with an _id of 5 (which doesn't contain an array) is also included:在以下输出中，请注意，_id为5的文档（不包含数组）也包含在内：

[
   {
      _id: 1,
      results: [ { product: 'abc', score: 10 }, { product: 'xyz', score: 5 } ]
   },
   {
      _id: 2,
      results: [ { product: 'abc', score: 8 }, { product: 'xyz', score: 7 } ]
   },
   {
      _id: 3,
      results: [ { product: 'abc', score: 7 }, { product: 'xyz', score: 8 } ]
   },
   { _id: 5, results: { product: 'xyz', score: 7 } }
]

Example 2示例2

Consider the following queries:考虑以下查询：

  • First query has a single <query> condition in $elemMatch.第一个查询在$elemMatch中只有一个<query>条件。
  • Second query omits $elemMatch.第二个查询省略了$elemMatch。

First query with $elemMatch:使用$elemMatch的第一个查询：

db.survey.find(
   { "results": { $elemMatch: { product: { $ne: "xyz" } } } }
)

The query returns documents that has a product with value other than "xyz":查询返回的文档中的product值不是"xyz"：

{ "_id" : 1, "results" : [ { "product" : "abc", "score" : 10 },
                           { "product" : "xyz", "score" : 5 } ] }
{ "_id" : 2, "results" : [ { "product" : "abc", "score" : 8 },
                           { "product" : "xyz", "score" : 7 } ] }
{ "_id" : 3, "results" : [ { "product" : "abc", "score" : 7 },
                           { "product" : "xyz", "score" : 8 } ] }
{ "_id" : 4, "results" : [ { "product" : "abc", "score" : 7 },
                           { "product" : "def", "score" : 8 } ] }

Second query without $elemMatch:第二个没有$elemMatch的查询：

db.survey.find(
   { "results.product": { $ne: "xyz" } }
)

The query returns documents where none of the product results are "xyz":查询results返回的文档中没有product是"xyz"：

{ "_id" : 4, "results" : [ { "product" : "abc", "score" : 7 },
                           { "product" : "def", "score" : 8 } ] }

Both queries include the document with an _id of 4, and omit the document with an _id of 5 because the product is "xyz".这两个查询都包括_id为4的文档，并省略_id为5的文档，因为它的product是"xyz"。

Learn More了解更多

For additional examples on querying arrays, see:有关查询数组的其他示例，请参阅：

For additional examples on querying, see Query Documents.有关查询的其他示例，请参阅查询文档。

Tip

db.collection.find()