$elemMatch (query)

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Exemplos
Saiba mais

O MongoDB 5.0 é o fim da vida útil a partir de de 2024 outubro. Esta versão da documentação não é mais suportada. Para atualizar sua 5.0 implantação do, consulte o MongoDB 6.0 procedimentos de atualização.

Dica

Veja também:

$elemMatch (projeção)

Definição

$elemMatch: O operador $elemMatch corresponde a documentos que contêm um campo de array com pelo menos um elemento que corresponde a todos os critérios de consulta especificados.

Compatibilidade

Você pode utilizar o $elemMatch para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

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

Comportamento

Não é possível especificar uma expressão $where em um $elemMatch.
Não é possível especificar uma expressão de query $text em um $elemMatch.

Exemplos

Correspondência de elemento

Dados os seguintes documentos na collection scores:

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

A query a seguir corresponde apenas aos documentos em que a array results contém pelo menos um elemento que é maior ou igual a 80 e menor que 85:

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

A query retorna o seguinte documento, pois o elemento 82 é maior ou igual a 80 e menor que 85:

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

Para obter mais informações sobre a especificação de vários critérios em elementos de array, consulte Especificar várias condições para elementos de array.

matriz de documentos incorporados

Esta declaração insere documentos na 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 } }
] )

O documento com um _id de 5 não contém uma array. Esse documento é incluído para mostrar que $elemMatch corresponde apenas aos elementos da array, que você verá nos exemplos a seguir.

A query a seguir corresponde a documentos em que results contém pelo menos um elemento em que product é "xyz" e score é maior ou igual a 8:

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

Especificamente, a query corresponde ao seguinte documento:

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

Condição de query única

As seções a seguir mostram as diferenças de saída quando você usa $elemMatch com uma única condição de consulta e omite $elemMatch.

Exemplo 1

Query com $elemMatch:

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

A query retorna documentos em que qualquer product em results é "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 sem $elemMatch:

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

Na saída a seguir, observe que o documento com uma _id de 5 (que não contém uma array) também está incluído:

[
   {
      _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 } }
]

Exemplo 2

Considere as seguintes queries:

A primeira query tem uma única condição <query> em $elemMatch.
A segunda query omite $elemMatch.

Primeira query com $elemMatch:

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

A query retorna documentos que têm um product com valor diferente de "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 } ] }

Segunda consulta sem $elemMatch:

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

A consulta retorna documentos onde nenhum dos product results é "xyz":

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

Ambas as queries incluem o documento com um _id de 4 e omitem o documento com um _id de 5 porque o product é "xyz".

Saiba mais

Para obter exemplos adicionais sobre como consultar arrays, consulte:

Para obter exemplos adicionais sobre queries, consulte Fazer query em documentos

Dica

Veja também:

db.collection.find()

Voltar

$tudo

$size