Especificar uma query

Visão geral

A maioria das operações CRUD permite que você restrinja o definir de documentos correspondentes especificando critérios correspondentes em um query document. Os documentos de query contêm um ou mais operadores de query que se aplicam a campos específicos que determinam quais documentos incluir no conjunto de resultados.

Em um documento de consulta, você pode combinar campos com valores literais, como { title: 'The Room' }, ou você pode compor operadores de consulta para expressar critérios de correspondência mais complexos. Neste guia, abordamos as seguintes categorias de operadores de consulta no MongoDB e mostramos exemplos sobre como usá-los:

• Operadores de comparação

• Operadores lógicos

• Operadores de elementos

• Operadores de avaliação

Para seguir os exemplos deste guia, utilize o seguinte snippet de código para inserir documentos que descrevem frutas na coleção myDB.fruits:

const myDB = client.db("myDB");
const myColl = myDB.collection("fruits");
await myColl.insertMany([
  { "_id": 1, "name": "apples", "qty": 5, "rating": 3 },
  { "_id": 2, "name": "bananas", "qty": 7, "rating": 1, "color": "yellow" },
  { "_id": 3, "name": "oranges", "qty": 6, "rating": 2 },
  { "_id": 4, "name": "avocados", "qty": 3, "rating": 5 },
]);

Consultas de valores literais

As queries de valores literais permitem que você query dados que correspondam exatamente a um valor fornecido no documento de query. Uma query de valor literal tem duas partes: um nome de campo e um valor. Os documentos retornados dessa query devem conter um campo que tenha exatamente o mesmo nome que o nome fornecido e um valor para esse campo que seja exatamente o mesmo que o valor fornecido. A operação a seguir usa uma query literal para procurar documentos que contenham um campo chamado "nome" que tenha um valor de "maçãs":

const query = { "name": "apples" };
const cursor = myColl.find(query);
for await (const doc of cursor) {
  console.dir(doc);
}

Este trecho de código retorna os seguintes resultados:

{ "_id": 1, "name": "apples", "qty": 5, "rating": 3 }

myColl.find({
   rating: { $eq: 5 }
});

myColl.find({
   rating: 5
});

Operadores de comparação

Os operadores de comparação permitem fazer consulta de dados com base em comparações com valores em uma coleção. Os operadores de comparação comuns incluem $gt para comparações "maior que", $lt para comparações "menor que" e $ne para comparações "não igual a". A operação a seguir usa o operador de comparação $gt para pesquisar documentos nos quais o valor do campo qty é maior que 5 e os imprime:

// $gt means "greater than"
const query = { qty: { $gt : 5 } };
const cursor = myColl.find(query);
for await (const doc of cursor) {
  console.dir(doc);
}

Este trecho de código retorna os seguintes resultados:

{ "_id": 2, "name": "bananas", "qty": 7, "rating": 1 }
{ "_id": 3, "name": "oranges", "qty": 6, "rating": 2 }

Operadores lógicos

Os operadores lógicos permitem fazer query de dados usando lógica aplicada aos resultados de operadores de nível de campo. Por exemplo, você pode utilizar o método $or para fazer query de documentos que correspondem a um operador de comparação do $gt ou a uma query de valor literal. A operação a seguir usa o operador lógico $not para pesquisar documentos com um valor de quantidade que não seja maior que 5 e os imprime:

const query = { qty: { $not: { $gt: 5 }}};
const cursor = myColl.find(query);
for await (const doc of cursor) {
  console.dir(doc);
}

Este trecho de código retorna os seguintes resultados:

{ "_id": 4, "name": "avocados", "qty": 3, "rating": 5 }
{ "_id": 1, "name": "apples", "qty": 5, "rating": 3 }

myColl.find({
  rating: { $eq: 5 },
  qty: { $gt: 4 }
});

myColl.find({
  $and: [
     { rating: { $eq: 5 }},
     { qty: { $gt: 4 }}
  ]
});

Para obter mais informações sobre operadores de comparação, consulte a entrada do manual de referência para Operadores de query de comparação.

Operadores de elementos

Os operadores de elemento permitem fazer query com base na presença, ausência ou tipo de campo. A operação a seguir usa o operador de elemento $exists para procurar documentos que contêm o campo color :

const query = { color: { $exists: true } };
const cursor = myColl.find(query);
for await (const doc of cursor) {
  console.dir(doc);
}

Este trecho de código retorna os seguintes resultados:

{ "_id": 2, "name": "bananas", "qty": 7, "rating": 1, "color": "yellow" }

Para obter mais informações sobre esse operador, consulte a entrada manual de referência para o operador $exists.

Operadores de avaliação

Os operadores de avaliação permitem que você execute lógica de nível superior, como pesquisas de regex e texto, ao fazer consulta de documentos em uma coleção. Operadores de avaliação comuns incluem $regex e $text. A operação a seguir usa o operador de avaliação $mod para pesquisar documentos em que o valor do campo qty é divisível por 3 com um restante de 0:

// $mod means "modulo" and returns the remainder after division
const query = { qty: { $mod: [ 3, 0 ] } };
const cursor = myColl.find(query);
for await (const doc of cursor) {
  console.dir(doc);
}

Este trecho de código retorna os seguintes resultados:

{ "_id": 3, "name": "oranges", "qty": 6, "rating": 2 }
{ "_id": 4, "name": "avocados", "qty": 3, "rating": 5 }

Para obter mais informações sobre esse operador, consulte a entrada manual de referência para o operador $mod.