/ /

Retrieve Data

Visão geral

Neste guia, você pode aprender como usar o Driver MongoDB .NET/C# para recuperar dados de uma coleção 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 MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte a Introdução ao driver .NET/C#.

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; }
    [BsonElement("restaurant_id")]
    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; }
    [BsonElement("coord")]
    public double[] Coordinates { get; set; }
    public string Street { get; set; }
    [BsonElement("zipcode")]
    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 collection restaurants usam a convenção de nomenclatura snake-case. 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 queries e retorna todos os documentos correspondentes. Um filtro de queries é um objeto que especifica os documentos que você deseja recuperar em sua query.

Para saber mais sobre filtros de query, consulte Criar um filtro de query.

Encontrar um documento

Para localizar um único documento em uma coleção, passe um filtro de queries 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 queries, esses métodos retornarão o primeiro documento correspondente dos resultados recuperados. Se nenhum documento corresponder ao filtro de queries, os métodos retornarão null.

var restaurants = _restaurantsCollection.Find(filter).FirstOrDefault();

var restaurants = await _restaurantsCollection.Find(filter).FirstOrDefaultAsync();

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 queries 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 queries 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 = _restaurantsCollection.Find(filter).ToCursor();

var restaurants = await _restaurantsCollection.Find(filter).ToCursorAsync();

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 encontrar vários documentos em uma coleção e mantê-los na memória como uma lista, passe um filtro de queries para o método Find() que especifique os critérios dos documentos que deseja encontrar 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 = _restaurantsCollection.Find(filter).ToList();

var restaurants = await _restaurantsCollection.Find(filter).ToListAsync();

Para ver um exemplo completo de como usar o método Find() para encontrar 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`	Obtém ou define o número máximo de documentos dentro de cada lote retornado em um resultado de query. Se `batchSize` não estiver definido, o método `Find()` terá um tamanho de lote inicial de `101` documentos e um tamanho máximo de 16 mebibytes (MiB) para cada lote subsequente. Esta opção pode impor um limite menor que 16 MiB, mas não maior. Se você definir `batchSize` para um limite que resulte em lotes maiores que 16 MiB, essa opção não terá efeito, e o método `Find()` usará o tamanho de lote padrão.
`Collation`	Define as opções de agrupamento. Consulte a seção Agrupamento desta página para obter mais informações.
`Comment`	Define o comentário para a query para facilitar a visualização nos registros do profiler .
`Hint`	Define a dica de qual índice usar.
`MaxTime`	Define o tempo de execução máximo no servidor para esta operação.

Para ver uma lista completa de opções disponíveis, consulte Propriedades do FindOptions.

Agrupamentos

Para configurar o agrupamento para sua operação, crie uma instância da classe Agrupamento.

A tabela seguinte descreve os parâmetros que o construtor do Collation aceita. Ela também lista a propriedade de classe correspondente que você pode usar para ler o valor de cada configuração.

Parâmetro	Descrição	Propriedade de classe
`locale`	Especifica a locale Componentes internacionais para Unicode (ICU). Para obter uma lista de localidades suportadas, consulte Localidades de Agrupamento e Parâmetros Padrão no Manual do MongoDB Server . Se você quiser usar a comparação binária simples, use a `Collation.Simple` propriedade estática para retornar um `Collation` objeto com o `locale` definido `"simple"` como. Tipo de dados: `string`	`Locale`
`caseLevel`	(Opcional) Especifica se incluir comparação de caso. Quando esse argumento `true` é, o comportamento do driver depende do valor do `strength` argumento: - Se `strength` `CollationStrength.Primary`for, o driver compara caracteres básicos e maiúsculas e minúsculas. - `strength` Se `CollationStrength.Secondary` for, o driver compara caracteres básicos, diacríticos, outras diferenças secundárias e maiúsculas e minúsculas. - Se `strength` for qualquer outro valor, esse argumento será ignorado. Quando esse argumento `false` é, o driver não inclui comparação de caso no nível de força `Primary` `Secondary`ou. Tipo de Dados: `boolean` Padrão: `false`	`CaseLevel`
`caseFirst`	(Opcional) Especifica a ordem de classificação das diferenças de caso durante as comparações de nível terciário. Tipo de dados: CollationCaseFirst padrão: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(Opcional) Especifica o nível de comparação a ser executado, conforme definido na documentação da ICU. Tipo de Dados: CollationStrength Padrão: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(Opcional) Especifica se o driver compara strings numéricas como números. Se esse argumento `true` for, o driver compara strings numéricas como números. Por exemplo, ao comparar as strings "10" e "2", o driver trata os valores como 10 e 2 e considera 10 maior. Se esse argumento for `false` ou excluído, o driver compara cadeias de caracteres numéricas como cadeias de caracteres. Por exemplo, ao comparar as strings "10" e "2", o driver compara um caractere de cada vez. Como "1" é menor que "2", o driver acha que "10" é menor que "2". Para obter mais informações, consulte Restrições de agrupamento no manual do MongoDB Server . Tipo de dados: `boolean` Padrão: `false`	`NumericOrdering`
`alternate`	(Opcional) Especifica se o driver considera o espaço em branco e a pontuação como caracteres básicos para fins de comparação. Tipo de dados: CollationAlterne padrão: `CollationAlternate.NonIgnorable` (espaços e pontuação são considerados caracteres básicos)	`Alternate`
`maxVariable`	(Opcional) Especifica quais caracteres o driver considera ignoráveis quando o `alternate` argumento `CollationAlternate.Shifted` é. Tipo de Dados: CollationMaxVariable Padrão: `CollationMaxVariable.Punctuation` (o driver ignora pontuação e espaços)	`MaxVariable`
`normalization`	(Opcional) Especifica se o driver normaliza o texto conforme necessário. A maioria dos textos não exige normalização. Para obter mais informações sobre normalização, consulte a documentação da ICU. Tipo de dados: `boolean` Padrão: `false`	`Normalization`
`backwards`	(Opcional) Especifica se as strings contendo diacríticos são classificadas da parte de trás da string para a frente. Tipo de dados: `boolean` Padrão: `false`	`Backwards`

Para obter mais informações sobre agrupamento, consulte a página Agrupamento no manual do MongoDB Server.

Exemplo

Este exemplo executa as seguintes ações:

Localiza todos os documentos com "Pizza" no campo cuisine
Define o BatchSize como 3
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

Crie um cursor com uma instrução usando para invocar automaticamente o método Dispose () quando o cursor não está mais em uso.

Informações adicionais

Para saber mais sobre filtros de query, consulte Criar um filtro de query.

Para saber como especificar queries usando LINQ, consulte Sintaxe LINQ para operações de agregação.

Para obter exemplos executáveis das operações de localização, consulte os seguintes exemplos de uso:

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:

Voltar

Especificar uma query

Especifique documentos a serem devolvidos