Visão geral
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:
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.
Encontrando 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: ...}, ... ]
Exemplo de findOne(): Arquivo Completo
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 objetotitle
eimdb
(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 } }
encontrar() Exemplo: Arquivo Completo
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 objetotitle
eimdb
(e seus campos embutidos).
1 import { MongoClient } from "mongodb"; 2 3 // Replace the uri string with your MongoDB deployment's connection string. 4 const uri = "<connection string uri>"; 5 6 const client = new MongoClient(uri); 7 8 async 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 } 37 run().catch(console.dir);
1 import { MongoClient } from "mongodb"; 2 3 // Replace the uri string with your MongoDB deployment's connection string. 4 const uri = "<connection string uri>"; 5 6 const client = new MongoClient(uri); 7 8 type Minutes = number; 9 10 interface IMDB { 11 rating: number; 12 votes: number; 13 id: number; 14 } 15 16 interface Movie { 17 title: string; 18 imdb: IMDB; 19 runtime: Minutes; 20 } 21 22 async 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 } 44 run().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.
Informações adicionais
Para obter mais informações sobre os métodos findOne()
e find()
, consulte a seguinte documentação manual do servidor:
Agregar dados de documentos
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 } ]
Informações adicionais
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.
Monitorar alterações de dados
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}.`); });
Informações adicionais
Para obter um exemplo executável do método watch()
, consulte a seção de exemplos no guia Monitorar dados com change streams.