$elemMatch (projeção)

Elemento retornado

O operador $ e também o operador $elemMatch projetam o primeiro elemento correspondente de uma array com base em uma condição.

O operador $ projeta o primeiro elemento de array correspondente de cada documento em uma collection com base em alguma condição da declaração de query.

O operador de projeção $elemMatch usa um argumento de condição explícita. Isso permite que você projete com base em uma condição que não esteja na query ou, se precisar projetar, com base em vários campos nos documentos incorporados da array. Consulte as Limitações de campos da array para ver um exemplo.

Ordem do campo

Independentemente da ordenação dos campos no documento, a projeção $elemMatch de um campo existente retorna o campo após as outras inclusões de campo existentes.

Por exemplo, considere uma collection players com o seguinte documento:

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")
} )

A projeção a seguir retorna o campo games após os outros campos existentes incluídos na projeção, embora no documento o campo esteja listado antes dos campos joined e lastLogin:

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

Ou seja, a operação retorna o seguinte documento:

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

Restrições

• As operações db.collection.find() nas visualizações não são compatíveis com o operador de projeção $elemMatch.

• Você não pode especificar um operador de consulta $text em um $elemMatch.

Pesquisa de CEP

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

 var results = schoolsCollection
     .Find(s => s.ZipCode == "63109")
     .Project(Builders<School>.Projection.ElemMatch(
         field: school => school.Students,
         filter: student => student.School == 102
    )
 ).ToList();

A operação retorna os seguintes documentos que têm um valor zipcode de "63109" e projeta a array students usando $elemMatch:

{ "_id" : 1, "students" : [ { "name" : "john", "school" : 102, "age" : 10 } ] }
{ "_id" : 3 }
{ "_id" : 4, "students" : [ { "name" : "barney", "school" : 102, "age" : 7 } ] }

• Para o documento com _id igual a 1, a array students contém vários elementos com o campo school igual a 102. No entanto, a projeção $elemMatch retorna somente o primeiro elemento correspondente da array.

• O documento com _id igual a 3 não contém o campo students no resultado, pois nenhum elemento em sua array students correspondeu à condição $elemMatch.

$elemMatch com vários campos

A projeção $elemMatch pode especificar critérios em vários campos.

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

var results = schoolsCollection
    .Find(s => s.ZipCode == "63109")
    .Project(Builders<School>.Projection.ElemMatch(
            field: school => school.Students,
            filter: student => (student.School == 102) && (student.Age > 10) 
        )
    ).ToList();

A operação retorna os três documentos que possuem um valor zipcode de "63109":

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

O documento com _id igual a 3 não contém o campo students já que nenhum elemento da array corresponde aos critérios $elemMatch.

O argumento para $elemMatch corresponde aos elementos da array que $elemMatch está projetando. Se você especificar uma igualdade com um nome de campo para $elemMatch, ele tentará corresponder a objetos dentro da array. Por exemplo, $elemMatch tenta combinar objetos, em vez de valores escalares, dentro da array para o seguinte na projeção:

db.schools.find( { zipcode: "63109" },
                { athletics: { $elemMatch: { athletics: "basketball" } } })

var results = schoolsCollection
    .Find(s => s.ZipCode == "63109")
    .Project(Builders<School>.Projection.ElemMatch(
            "athletics",
            Builders<School>.Filter.Eq("athletics", "basketball"))
    ).ToList();

Os exemplos anteriores retornam os documentos que têm um zipcode valor de "63109", mas esses documentos incluem apenas o _id campo porque a operação de projeção não encontrou elementos correspondentes.

db.schools.find( { zipcode: "63109" },
                { athletics: { $elemMatch: { $eq: "basketball" } } })

var results = schoolsCollection
    .Find(s => s.ZipCode == "63109")
    .Project(Builders<School>.Projection.ElemMatch(
        field: "athletics",
        filter: Builders<School>.Filter.Eq("$eq", "basketball"))
    ).ToList();

A operação retorna os três documentos que têm o valor zipcode de "63109". Os documentos retornados incluem o campo _id e os elementos correspondentes do array athletics, se existirem.

[
   { _id: 1 },
   { _id: 3, athletics: [ 'basketball' ] },
   { _id: 4 }
]

O documento com _id igual a 3 é o único documento que corresponde aos critérios $elemMatch .