Join us Sept 17 at .local NYC! Use code WEB50 to save 50% on tickets. Learn more >
MongoDB Event
Menu Docs
Página inicial do Docs
/ / /
Controlador Node.js
/ /

Encontrar documentos

Você pode executar operações para recuperar dados de seu banco de dados MongoDB. Você pode executar uma operação de localizar para corresponder aos documentos em um conjunto de critérios ligando com o método find() ou findOne().

Dica

Laboratório interativo

Esta página inclui um breve laboratório interativo que demonstra como recuperar dados usando o método find(). Você pode concluir este laboratório diretamente na janela do seu navegador sem instalar o MongoDB nem um editor de código.

Para iniciar o laboratório, clique no botão Open Interactive Tutorial na parte superior da página. Para expandir o laboratório para um formato de tela inteira, clique no botão de tela inteira () no canto superior direito do painel do laboratório.

Você também pode especificar melhor as informações que a operação de localização retorna especificando parâmetros opcionais ou encadeando outros métodos, conforme mostrado nos seguintes guias:

  • Especifique documentos a serem devolvidos

  • Especifique quais campos retornar

Você também pode utilizar uma operação de aggregation para recuperar dados. Esse tipo de operação permite que você aplique um pipeline ordenado de transformações aos dados correspondentes.

Se você deseja monitorar o banco de dados para dados de entrada que correspondem a um conjunto de critérios, você pode usar a operação de relógio para ser notificado em tempo real quando dados correspondentes são inseridos.

Observação

Sua operação de query pode retornar uma referência a um cursor que contém documentos correspondentes. Para saber como examinar os dados armazenados no cursor, consulte a página Acessar dados de um cursor.

Você pode usar o driver Node.js para conectar e executar operações de leitura 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

Para saber mais sobre como executar operações de leitura na IU do Atlas para implantações hospedadas no MongoDB Atlas, consulte Exibir, Filtrar e Classificar Documentos.

Você pode usar o método find() em um objeto Collection. O método aceita um documento de query que descreve os documentos que você deseja recuperar. Para saber mais sobre como especificar seu documento de query, consulte o guia Especificar uma query.

Dica

Nenhum critério de query

Para executar uma operação de localização que não tenha critérios de query, você pode passar uma query vazia ou omitir o documento de query nos parâmetros do método de busca.

As seguintes operações retornam todos os documentos na collection myColl:

myColl.find(); // no query
myColl.find({}); // empty query

Se você não passar uma query ou passar uma query vazia para o método findOne(), a operação retornará um único documento de uma collection.

Você pode encadear métodos de cursor para uma operação de busca mesmo quando você passa por uma query vazia. Por exemplo, o código a seguir mostra como você pode especificar uma projeção ao executar uma operação de busca que recebe um parâmetro de query vazia:

const projectFields = { _id: 0, field1: 1 };
const findResult = await myColl.findOne().project(projectFields);

Para obter mais informações sobre a projeção de campos de documentos, consulte o guia Especificar quais campos devem ser retornados.

O método find() retorna uma instância Cursor da qual você pode acessar os documentos correspondentes. O método findOne() retorna uma instância Promise , que pode ser resolvida para acessar o documento correspondente ou um valor null se não houver correspondências.

Exemplo

Uma pizzaria quer encontrar todas as pizzas encomendadas por Lemony Snicket ontem. Eles executam a seguinte query find() na collection orders:

// Search for orders by name and within a specific date range
const findResult = orders.find({
name: "Lemony Snicket",
date: {
$gte: new Date(new Date().setHours(00, 00, 00)),
$lt: new Date(new Date().setHours(23, 59, 59)),
},
});

Após a operação retornar, a variável findResult faz referência a Cursor. Você pode imprimir os documentos recuperados utilizando a sintaxe for await...of como mostrado abaixo:

for await (const doc of findResult) {
console.log(doc);
}

O resultado pode se assemelhar ao seguinte:

[
{ name: "Lemony Snicket", type: "horseradish pizza", qty: 1, status: "delivered", date: ... },
{ name: "Lemony Snicket", type: "coal-fired oven pizza", qty: 3, status: "canceled", date: ...},
...
]

Observação

Exemplo de configuração

Esse exemplo se conecta a uma instância do MongoDB usando um URI de conexão. Para saber mais sobre como se conectar à sua instância do MongoDB, consulte o guia Conectar ao MongoDB. Este exemplo também utiliza a coleção do movies no banco de dados do sample_mflix incluído nos conjuntos de dados de amostra do Atlas. Você pode carregá-los em seu banco de dados na camada grátis do MongoDB Atlas seguindo o Guia de Introdução ao Atlas.

O exemplo de arquivo completo a seguir encontra um único documento da coleção movies. Ele usa os seguintes parâmetros:

  • Filtro que corresponde a documentos nos quais o valor title é 'The Room'.

  • Classificação que organiza documentos correspondentes em ordem decrescente por classificação; portanto, se nossa query corresponder a vários documentos, o documento retornado será o documento com a classificação mais alta.

  • Projeção que exclui explicitamente o campo _id dos documentos retornados e inclui explicitamente apenas o objeto title e imdb (e seus campos embutidos).

import { MongoClient } from "mongodb";
// Replace the uri string with your MongoDB deployment's connection string.
const uri = "<connection string uri>";
const client = new MongoClient(uri);
async function run() {
try {
// Get the database and collection on which to run the operation
const database = client.db("sample_mflix");
const movies = database.collection("movies");
// Query for a movie that has the title 'The Room'
const query = { title: "The Room" };
const options = {
// Sort matched documents in descending order by rating
sort: { "imdb.rating": -1 },
// Include only the `title` and `imdb` fields in the returned document
projection: { _id: 0, title: 1, imdb: 1 },
};
// Execute query
const movie = await movies.findOne(query, options);
// Print the document returned by findOne()
console.log(movie);
} finally {
await client.close();
}
}
run().catch(console.dir);
import { MongoClient } from "mongodb";
// Replace the uri string with your MongoDB deployment's connection string.
const uri = "<connection string uri>";
const client = new MongoClient(uri);
interface IMDB {
rating: number;
votes: number;
id: number;
}
export interface Movie {
title: string;
year: number;
released: Date;
plot: string;
type: "movie" | "series";
imdb: IMDB;
}
type MovieSummary = Pick<Movie, "title" | "imdb">;
async function run(): Promise<void> {
try {
const database = client.db("sample_mflix");
// Specifying a Schema is always optional, but it enables type hinting on
// finds and inserts
const movies = database.collection<Movie>("movies");
const movie = await movies.findOne<MovieSummary>(
{ title: "The Room" },
{
sort: { rating: -1 },
projection: { _id: 0, title: 1, imdb: 1 },
}
);
console.log(movie);
} finally {
await client.close();
}
}
run().catch(console.dir);

Ao executar o exemplo anterior, você verá a seguinte saída:

{ title: 'The Room', imdb: { rating: 3.5, votes: 25673, id: 368226 } }

Observação

Exemplo de configuração

Esse exemplo se conecta a uma instância do MongoDB usando um URI de conexão. Para saber mais sobre como se conectar à sua instância do MongoDB, consulte o guia Conectar ao MongoDB. Este exemplo também utiliza a coleção do movies no banco de dados do sample_mflix incluído nos conjuntos de dados de amostra do Atlas. Você pode carregá-los em seu banco de dados na camada grátis do MongoDB Atlas seguindo o Guia de Introdução ao Atlas.

O exemplo de arquivo completo a seguir encontra documentos da coleção movies. Ele usa os seguintes parâmetros:

  • Filtro que corresponde a documentos em que o valor de runtime é menor que 15 minutos.

  • Classificação que organiza documentos devolvidos em ordem crescente por título (ordem alfabética em que "A" vem antes de "Z" e "1" antes de "9").

  • Projeção que exclui explicitamente o campo _id dos documentos retornados e inclui explicitamente apenas o objeto title e imdb (e seus campos embutidos).

1import { MongoClient } from "mongodb";
2
3// Replace the uri string with your MongoDB deployment's connection string.
4const uri = "<connection string uri>";
5
6const client = new MongoClient(uri);
7
8async function run() {
9 try {
10
11 // Get the database and collection on which to run the operation
12 const database = client.db("sample_mflix");
13 const movies = database.collection("movies");
14
15 // Query for movies that have a runtime less than 15 minutes
16 const query = { runtime: { $lt: 15 } };
17 const sortFields = { title: 1 };
18 const projectFields = { _id: 0, title: 1, imdb: 1 };
19
20 // Execute query
21 const cursor = movies.find(query).sort(sortFields).project(projectFields);
22
23 // Print a message if no documents were found
24 if ((await movies.countDocuments(query)) === 0) {
25 console.log("No documents found!");
26 }
27
28 // Print returned documents
29 for await (const doc of cursor) {
30 console.dir(doc);
31 }
32
33 } finally {
34 await client.close();
35 }
36}
37run().catch(console.dir);
1import { MongoClient } from "mongodb";
2
3// Replace the uri string with your MongoDB deployment's connection string.
4const uri = "<connection string uri>";
5
6const client = new MongoClient(uri);
7
8type Minutes = number;
9
10interface IMDB {
11 rating: number;
12 votes: number;
13 id: number;
14}
15
16interface Movie {
17 title: string;
18 imdb: IMDB;
19 runtime: Minutes;
20}
21
22async function run() {
23 try {
24 const database = client.db("sample_mflix");
25 const movies = database.collection<Movie>("movies");
26
27 const query = { runtime: { $lt: 15 } };
28 const sortFields = { title: 1 };
29 const projectFields = { _id: 0, title: 1, imdb: 1 };
30
31 const cursor = movies.find<Movie>(query).sort(sortFields).project(projectFields);
32
33 if ((await movies.countDocuments(query)) === 0) {
34 console.warn("No documents found!");
35 }
36
37 for await (const doc of cursor) {
38 console.dir(doc);
39 }
40 } finally {
41 await client.close();
42 }
43}
44run().catch(console.dir);

Ao executar o exemplo anterior, você verá a seguinte saída:

{ title: '10 Minutes', imdb: { rating: 7.9, votes: 743, id: 339976 } }
{ title: '3x3', imdb: { rating: 6.9, votes: 206, id: 1654725 } }
{ title: '7:35 in the Morning', imdb: { rating: 7.3, votes: 1555, id: 406501 } }
{ title: '8', imdb: { rating: 7.8, votes: 883, id: 1592502 } }
...

Observação

Você deve encadear um método de cursor como sort(), limit(), skip() ou project() a uma operação de leitura antes de iterar o cursor. Se você especificar um método de cursor após iterar o cursor, a configuração não se aplicará à operação de leitura.

Para obter mais informações sobre os métodos findOne() e find(), consulte a seguinte documentação manual do servidor:

Se quiser executar um pipeline de processamento personalizado para recuperar dados do seu banco de dados, você pode utilizar o método aggregate(). Este método aceita expressões de aggregation para executar em sequência. Essas expressões permitem filtrar, agrupar e organizar os dados de resultado de uma collection.

Exemplo

Uma pizzaria quer executar um relatório de status on-demand para resumir os pedidos de pizza na semana passada. Eles executam a seguinte query aggregate() na collection orders para obter os totais para cada campo "status" distinto:

// Group orders by status within the last week
const aggregateResult = orders.aggregate([
{
$match: {
date: {
$gte: new Date(new Date().getTime() - 1000 * 3600 * 24 * 7),
$lt: new Date(),
},
},
},
{
$group: {
_id: "$status",
count: {
$sum: 1,
},
},
},
]);

Após a operação retornar, a variável aggregateResult faz referência a Cursor. Você pode imprimir os documentos recuperados utilizando a sintaxe for await...of como mostrado abaixo:

for await (const doc of aggregateResult) {
console.log(doc);
}

O resultado pode se assemelhar ao seguinte:

[
{ _id: 'delivering', count: 5 },
{ _id: 'delivered', count: 37 },
{ _id: 'created', count: 9 }
]

Para obter mais informações sobre como construir um pipeline de agregação, consulte o guia Operações de agregação ou Operações de agregação no manual do servidor.

Você pode usar o método watch() para monitorar uma collection para alterações em uma collection que correspondam a determinados critérios. Essas alterações incluem documentos inseridos, atualizados, substituídos e excluídos. Você pode passar a esse método um pipeline de comandos de aggregation que é executado sequencialmente nos dados alterados sempre que operações de gravação forem executadas na collection.

Exemplo

Uma pizzaria quer receber uma notificação sempre que um novo pedido de pizza chegar. Para fazer isso, eles criam um pipeline de aggregation para filtrar as operações de inserção e retornar campos específicos. Eles passam esse pipeline para o método watch() chamado na collection orders conforme mostrado abaixo:

// Set up a change stream to listen for new order insertions
const changeStream = orders.watch([
{ $match: { operationType: "insert" } },
{
$project: {
"fullDocument.name": 1,
"fullDocument.address": 1,
},
},
]);
changeStream.on("change", change => {
const { name, address } = change.fullDocument;
console.log(`New order for ${name} at ${address}.`);
});

Para obter um exemplo executável do método watch(), consulte a seção de exemplos no guia Monitorar dados com change streams.

Voltar

Consultar documentos

Nesta página