Recuperar dados
Nesta página
Visão geral
Neste guia, você aprenderá a usar o driver .NET/C# do MongoDB para recuperar dados de uma coleção do MongoDB usando operações de leitura. Você pode chamar o método Find()
para recuperar documentos que correspondam a um conjunto de critérios.
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.
Dados de amostra
Os exemplos neste guia usam a collection sample_restaurants.restaurants
dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte o Início rápido.
Os exemplos desta página utilizam as seguintes classes Restaurant
, Address
e GradeEntry
como modelos:
public class Restaurant { public ObjectId Id { get; set; } public string Name { get; set; } [ ] public string RestaurantId { get; set; } public string Cuisine { get; set; } public Address Address { get; set; } public string Borough { get; set; } public List<GradeEntry> Grades { get; set; } }
public class Address { public string Building { get; set; } [ ] public double[] Coordinates { get; set; } public string Street { get; set; } [ ] public string ZipCode { get; set; } }
public class GradeEntry { public DateTime Date { get; set; } public string Grade { get; set; } public float? Score { get; set; } }
Observação
Os documentos na coleção restaurants
usam a convenção de nomenclatura de camelo. Os exemplos neste guia usam um ConventionPack
para desserializar os campos na coleção em maiúsculas e minúsculas Pascal e mapeá-los para as propriedades na classe Restaurant
.
Para saber mais sobre serialização personalizada, consulte Serialização personalizada.
Encontrar documentos
Use o método Find()
para recuperar documentos de uma coleção. O método Find()
utiliza um filtro de query e retorna todos os documentos correspondentes. Um filtro de query é um objeto que especifica os documentos que você deseja recuperar em sua query.
Para saber mais sobre filtros de query, consulte Especificar uma query.
Encontrar um documento
Para localizar um único documento em uma coleção, passe um filtro de query que especifique os critérios do documento que você deseja localizar e, em seguida, encadeie o método FirstOrDefault()
ou FirstOrDefaultAsync()
. Se mais de um documento corresponder ao filtro de query, esses métodos retornarão o primeiro documento correspondente dos resultados recuperados. Se nenhum documento corresponder ao filtro de query, os métodos retornarão null
.
var restaurants = await _restaurantsCollection.Find(filter).FirstOrDefaultAsync();
var restaurants = _restaurantsCollection.Find(filter).FirstOrDefault();
Dica
Primeiro documento
O método FirstOrDefault()
retorna o primeiro documento em ordem natural no disco se nenhum critério de classificação for especificado.
Para ver um exemplo completo de como usar o método Find()
para localizar um único documento, consulte Outras informações.
Localizar vários documentos
Para encontrar vários documentos em uma coleção, passe um filtro de query para o método Find()
que especifica os critérios dos documentos que você deseja recuperar.
Você pode utilizar um cursor para iterar nos documentos retornados pelo método Find()
. Um cursor é um mecanismo que permite que um aplicativo itere sobre os resultados do banco de dados enquanto mantém apenas um subconjunto deles na memória em determinado momento. Os cursores são úteis quando o método Find()
retorna uma grande quantidade de documentos.
Para usar um cursor para iterar sobre os documentos, passe um filtro de query para o método Find()
que especifica os critérios dos documentos que você deseja localizar e, em seguida, encadeie o método ToCursor()
ou ToCursorAsync()
. Para visualizar um exemplo síncrono ou assíncrono, selecione a guia correspondente.
var restaurants = await _restaurantsCollection.Find(filter).ToCursorAsync();
var restaurants = _restaurantsCollection.Find(filter).ToCursor();
Se você for retornar um pequeno número de documentos ou precisar que seus resultados sejam retornados como um objeto List
, use os métodos ToList()
ou ToListAsync()
.
Para localizar vários documentos em uma coleção e mantê-los na memória como uma lista, passe um filtro de query para o método Find()
que especifique os critérios dos documentos que deseja localizar e, em seguida, encadeie o método ToList()
ou ToListAsync()
. Para visualizar um exemplo síncrono ou assíncrono, selecione a guia correspondente.
var restaurants = await _restaurantsCollection.Find(filter).ToListAsync();
var restaurants = _restaurantsCollection.Find(filter).ToList();
Para ver um exemplo completo de como usar o método Find()
para localizar vários documentos, consulte Informações adicionais.
Observação
Localizar todos os documentos
Para encontrar todos os documentos em uma coleção, passe um filtro vazio para o método Find()
.
var filter = Builders<Restaurant>.Filter.Empty; var allRestaurants = _restaurantsCollection.Find(filter);
Para ver um exemplo totalmente executável do uso do método Find()
para localizar todos os documentos, consulte Informações adicionais.
Modificar comportamento de localização
Você pode modificar o comportamento do método Find()
passando um objeto FindOptions
.
Você pode configurar as opções comumente usadas com os seguintes métodos:
Método | Descrição |
---|---|
BatchSize | Gets or sets the number of documents to hold in a cursor at a given time. |
Collation | Sets the collation options. |
Comment | Sets the comment to the query. To learn more about query comments,
see the $comment page. |
Hint | Sets the hint for which index to use. |
MaxTime | Sets the maximum execution time on the server for this operation. |
Para ver uma lista completa de opções disponíveis, consulte Propriedades do FindOptions.
Exemplo
Este exemplo executa as seguintes ações:
Localiza todos os documentos com "Pizza" no campo
cuisine
Define o
BatchSize
como3
Armazena os resultados em um cursor
Imprime os documentos referenciados pelo cursor
var filter = Builders<Restaurant>.Filter.Eq("cuisine", "Pizza"); var findOptions = new FindOptions { BatchSize = 3 }; using (var cursor = _restaurantsCollection.Find(filter, findOptions).ToCursor()) { foreach (var r in cursor.ToEnumerable()) { WriteLine(r.Name); } }
Pizza Town Victoria Pizza ...
Dica
Limpeza
Criar um cursor com uma declaração de uso para invocar automaticamente o Dispose () método quando o cursor não está mais em uso.
Informações adicionais
Para saber mais sobre filtros de query, consulte Especificar uma query.
Para saber como especificar queries usando LINQ, consulte LINQ.
Para exibir exemplos executáveis do método Find()
, consulte a página Localizar um documento.
Documentação da API
Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API: