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.

In a query document, you can match fields against literal values, such as { title: 'The Room' }, or you can compose query operators to express more complex matching criteria. In this guide, we cover the following categories of query operators in MongoDB and show examples on how to use them:

• 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 }}
  ]
});

For more information on comparison operators, see the reference manual entry for Comparison Query Operators.

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 queries de regex e texto, ao fazer query 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 realizar a pesquisa de documentos nos quais 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 }

For more information on this operator, see the reference manual entry for the $mod operator.