Atlas Search

Nesta página

Visão geral

criar um índice do atlas search
Atlas Search Operators
Autocompletar
composto
Iguais
Existe
GeoShape
GeoWithin
MoreLikeThis
Aproximar
Frase
QueryString
faixa
expressão regular
Espanha
Text
Curinga

Esta versão da documentação foi arquivada e não é mais suportada. Leia adocumentação atual para saber como atualizar sua versão do driver .NET/C#.

Visão geral

Neste guia, você aprenderá a usar o construtor Search para criar um estágio de pipeline de agregação $search com o driver .NET/C# do MongoDB.

Para saber mais sobre a $search pipeline stage, consulte $search.

Observação

Disponível apenas no Atlas para MongoDB v4.2 e posterior

O operador de pipeline de agregação $search está disponível somente para coleções hospedadas em clusters do MongoDB Atlas que executam o MongoDB v4.2 ou posterior que são abrangidos por um índice do Atlas Search. Para saber mais sobre a configuração necessária e a funcionalidade desse operador, consulte a documentação do Atlas Search .

Os exemplos deste guia usam os seguintes documentos em uma collection chamada guitars:

{ "_id": 1, "make": "Fender", "description": "Classic guitars known for their versatility.", "establishedYear": 1946, "in-stock": true, "rating": 9 }
{ "_id": 2, "make": "Gibson", "description": "Classic guitars known for their rich, full tones.", "establishedYear": 1902, "in-stock": true, "rating": 8 }
{ "_id": 3, "make": "PRS", "description": "High-end guitars known for their quality.", "establishedYear": 1985, "in-stock": true, "rating": 9 }
{ "_id": 4, "make": "Kiesel", "description": "Quality guitars made only for custom orders.", "establishedYear": 2015, "in-stock": false }
{ "_id": 5, "make": "Ibanez", "description": "Well-crafted guitars used by many professional guitarists.", "establishedYear": 1957, "in-stock": true, "rating": 7 }
{ "_id": 6, "make": "Strandberg", "description": "Modern guitars known for their headless models.", "establishedYear": 1982, "in-stock": false }

A seguinte classe Guitar modela os documentos nesta collection.

public class Guitar
{
    public int Id { get; set; }
    public string Make { get; set; }
    public List<string> Models { get; set; }
    public int EstablishedYear { get; set; }
    [BsonElement("in-stock")]
    public bool InStock { get; set; }
    public int? Rating { get; set; }
}

Observação

Os documentos na coleção guitars 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 Guitar .

Para saber mais sobre serialização personalizada, consulte Serialização personalizada.

criar um índice do atlas search

Antes de executar uma pesquisa em uma coleção do Atlas, primeiro você deve criar um índice do Atlas Search na coleção. Um índice do Atlas Search é uma estrutura de dados que categoriza os dados em um formato pesquisável.

Para saber como criar um Atlas Search Index, consulte o guia Criar um Atlas Search Index do Atlas.

Atlas Search Operators

A classe Search contém métodos que você pode utilizar para executar operações do $search. Para obter uma lista completa das operadoras $search disponíveis, consulte o guia do Atlas de Operadoras e Coletoras.

Observação

A classe Search não suporta atualmente o operador $embeddedDocument.

Autocompletar

Use o método Autocomplete para pesquisar uma palavra ou frase que contenha uma sequência de caracteres de uma string de entrada incompleta.

O exemplo seguinte executa uma pesquisa de preenchimento automático na coleção guitars utilizando a string "Gib" no campo make.

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Autocomplete(g => g.Make, "Gib"))
    .ToList();

A pesquisa retorna o seguinte documento:

{ "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }

Para saber mais sobre o operador autocomplete , consulte o guia do Atlas de preenchimento automático.

composto

Use o método Compound para combinar dois ou mais operadores em uma única pesquisa.

O exemplo seguinte pesquisa a coleção guitars por quaisquer documentos que correspondam a todos os seguintes critérios:

O campo rating existe no documento
O campo in-stock não é false
O campo establishedYear tem um valor superior a 1940

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Compound()
        .Must(Builders<Guitar>.Search.Exists(g => g.Rating))
        .MustNot(Builders<Guitar>.Search.Equals(g => g.InStock, false))
        .Must(Builders<Guitar>.Search.Range(g => g.EstablishedYear, SearchRangeBuilder.Gt(1940))))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in-stock" : true, "rating" : 9 }
{ "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in-stock" : true, "rating" : 7 }

Para saber mais sobre o operador compound, consulte o guia Atlas composto.

Iguais

Utilize o método Equals para verificar se um campo corresponde a um valor especificado.

O exemplo a seguir pesquisa a coleção guitars para quaisquer documentos nos quais o valor do campo in-stock é true.

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Equals(g => g.InStock, true))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 2, "make" : "Gibson", "description" : "...", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }
{ "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in-stock" : true, "rating" : 9 }
{ "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in-stock" : true, "rating" : 7 }

Para saber mais sobre o operador equals, consulte o guia equals do Atlas.

Existe

Use o método Exists para pesquisar documentos nos quais existe um nome de campo indexado especificado. Se o campo especificado existir, mas não estiver indexado, o documento não será incluído com o conjunto de resultados.

O exemplo a seguir pesquisa na coleção guitars quaisquer documentos nos quais o campo rating exista.

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Exists(g => g.Rating))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 2, "make" : "Gibson", "description" : "...", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }
{ "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in-stock" : true, "rating" : 9 }
{ "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in-stock" : true, "rating" : 7 }

Para saber mais sobre o operador exists, consulte o guia do Atlas existente.

GeoShape

Use o método GeoShape para pesquisar documentos em relação a uma determinada geometria. Ao especificar as coordenadas a serem pesquisadas, a longitude deve ser especificada primeiro e, em seguida, a latitude. Os valores de longitude podem estar entre -180 e 180. Os valores de latitude podem estar entre -90 e 90.

Observação

O Atlas Search não oferece suporte ao seguinte:

Sistema de Referência de Coordenadas Não Padrão (CRS)
Sistema de coordenadas Planar XY (bidimensional)
Notação de Ponto de pares de coordenadas (pointFieldName: [12, 34])

Considere que alguns documentos na coleção guitars adicionaram um campo in-stock-location. Os documentos alterados na coleção agora têm a seguinte aparência:

{ "_id": 1, "make": "Fender", "description": "...", "establishedYear": 1946, "in-stock": true, "in-stock-location":  { "type": "Point", "coordinates": [ -73.93615, 40.69791 ]}, "rating": 9 }
{ "_id": 2, "make": "Gibson", "description": "...", "establishedYear": 1902, "in-stock": true, "in-stock-location":  { "type": "Point", "coordinates": [ 47.6062, 122.321 ]}, "rating": 8 }

O seguinte exemplo pesquisa todos os documentos em que as coordenadas no campo in-stock-location interseccionam com um polígono especificado:

GeoJsonPolygon<GeoJson2DGeographicCoordinates> searchArea = new(new(new(new GeoJson2DGeographicCoordinates[]
{
     new(-72.93615, 41.69791),
     new(-72.93615, 40.59791),
     new(-74.93615, 40.59791),
     new(-74.93615, 41.69791),
     new(-72.93615, 41.69791),
})));
var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.GeoShape(g => g.InStockLocation, GeoShapeRelation.Intersects, searchArea))
    .ToList();

A pesquisa retorna o seguinte documento:

{ "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in-stock" : true, "in-stock-location" : { "type" : "Point", "coordinates" : ["-73.93615", "40.69791"] }, "rating" : 9 }

Para saber mais sobre o operador geoShape, consulte o guia geoShape do Atlas.

GeoWithin

Use o método GeoWithin para pesquisar documentos nos quais as coordenadas de seu campo GeoJSON especificado estão dentro de uma determinada geometria. Você pode pesquisar pontos que estão dentro de:

Círculo
Caixa delimitadora
Polígono

Ao especificar as coordenadas a serem pesquisadas, a longitude deve ser especificada primeiro, seguida da latitude. Os valores de longitude podem estar entre -180 e 180, inclusive. Os valores de latitude podem estar entre -90 e 90, inclusive.

Observação

O Atlas Search não oferece suporte ao seguinte:

Sistema de Referência de Coordenadas Não Padrão (CRS)
Sistema de coordenadas Planar XY (bidimensional)
Notação de Ponto de pares de coordenadas (pointFieldName: [12, 34])

Considere que alguns documentos na coleção guitars adicionaram um campo in-stock-location. Os documentos alterados na coleção agora têm a seguinte aparência:

{ "_id": 1, "make": "Fender", "description": "...", "establishedYear": 1946, "in-stock": true, "in-stock-location":  { "type": "Point", "coordinates": [ -73.93615, 40.69791 ]}, "rating": 9 }
{ "_id": 2, "make": "Gibson", "description": "...", "establishedYear": 1902, "in-stock": true, "in-stock-location":  { "type": "Point", "coordinates": [ 47.6062, 122.321 ]}, "rating": 8 }

O exemplo a seguir pesquisa todos os documentos em que as coordenadas do campo in-stock-location estejam dentro de um determinado polígono:

GeoJsonPolygon<GeoJson2DGeographicCoordinates> searchArea = new(new(new(new GeoJson2DGeographicCoordinates[]
{
     new(-74.3994140625, 40.5305017757),
     new(-74.7290039063, 40.5805846641),
     new(-74.7729492188, 40.9467136651),
     new(-74.0698242188, 41.1290213475),
     new(-73.65234375, 40.9964840144),
     new(-72.6416015625, 40.9467136651),
     new(-72.3559570313, 40.7971774152),
     new(-74.3994140625, 40.5305017757),
})));
var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.GeoWithin(g => g.InStockLocation, searchArea))
    .ToList();

A pesquisa retorna o seguinte documento:

{ "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in-stock" : true, "in-stock-location" : { "type" : "Point", "coordinates" : ["-73.93615", "40.69791"] }, "rating" : 9 }

Para saber mais sobre o operador geoWithin , consulte o guia geoWithin Atlas.

MoreLikeThis

Use o método MoreLikeThis para pesquisar documentos semelhantes a um documento de entrada.

O exemplo abaixo pesquisa documentos na collection guitars que sejam semelhantes a um objeto no qual o valor do campo Description seja de "alta qualidade".

var searchDocument = new GuitarSearch()
{
    Description = "high quality",
};
var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.MoreLikeThis(searchDocument))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 3, "make" : "PRS", "description" : "High-end guitars known for their quality.", "establishedYear" : 1985, "in-stock" : true, "rating" : 9 }
{ "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in-stock" : false, "rating" : null }

Para saber mais sobre o operador do moreLikeThis, consulte o guia do Atlas moreLikeThis .

Aproximar

Use o método Near para pesquisar documentos nos quais um campo especificado está próximo de um determinado valor. Você pode realizar a pesquisa em:

Um campo de número
Um campo de data
Um ponto geográfico

O exemplo a seguir pesquisa a coleção guitars em busca de documentos nos quais o valor do campo rating esteja próximo 9. Os documentos são retornados em ordem com base na proximidade do valor do número 9.

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Near(g => g.Rating, 9, 1))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in-stock" : true, "rating" : 9 }
{ "_id" : 2, "make" : "Gibson", "description" : "...", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }
{ "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in-stock" : true, "rating" : 7 }

To learn more about the near operator, see the near Atlas guide.

Frase

Use o método Phrase para pesquisar documentos nos quais um campo especificado contém uma string de entrada.

O exemplo a seguir pesquisa na coleção guitars os documentos em que o campo description contém a frase "classic guitars."

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Phrase(g => g.Description, "classic guitars"))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }

Você também pode pesquisar na coleção documentos que correspondam a várias frases separadas, da seguinte forma:

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Phrase(g => g.Description, new List<string>() { "classic guitars", "quality guitars" }))
    .ToList();

Esta pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in-stock" : false, "rating" : null }
{ "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }

Para saber mais sobre o operador phrase , consulte a frase Guia do Atlas.

QueryString

Use o método QueryString para pesquisar documentos usando uma string com os seguintes operadores e delimitadores:

AND
OR
NOT
()

O exemplo a seguir pesquisa na coleção guitars documentos nos quais o valor do campo description corresponda a cada um dos seguintes critérios:

Contém a string "clássica" ou a string "qualidade"
Não contém a string "personalizado"

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.QueryString(g => g.Description, "(classic OR quality) AND NOT custom"))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 3, "make" : "PRS", "description" : "High-end guitars known for their quality.", "establishedYear" : 1985, "in-stock" : true, "rating" : 9 }
{ "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }

Para saber mais sobre o operador queryString, consulte o guia queryString do Atlas.

faixa

Use o método Range para pesquisar documentos nos quais o valor de um campo especificado esteja dentro de um determinado intervalo numérico ou de datas.

O exemplo a seguir pesquisa na coleção guitars todos os documentos com um valor establishedYear maior que 1980 e menor que 2020.

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Range(g => g.EstablishedYear, SearchRangeBuilder.Gt(1980).Lt(2020)))
    .ToList();

A pesquisa retorna os seguintes resultados:

{ "_id" : 3, "make" : "PRS", "description" : "High-end guitars known for their quality.", "establishedYear" : 1985, "in-stock" : true, "rating" : 9 }
{ "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in-stock" : false, "rating" : null }
{ "_id" : 6, "make" : "Strandberg", "description" : "Modern guitars known for their headless models.", "establishedYear" : 1982, "in-stock" : false, "rating" : null }

Para saber mais sobre o operador range, consulte o guia Atlas de intervalos.

expressão regular

Use o método Regex para pesquisar documentos usando uma expressão regular.

O exemplo seguinte pesquisa a coleção guitars para documentos em que o valor do campo make contém exatamente seis letras.

var regex = "[A-Za-z]{6}";
var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Regex(g => g.Make, regex))
    .ToList();

A pesquisa retorna os seguintes resultados:

{ "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in-stock" : true, "rating" : 9 }
{ "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in-stock" : true, "rating" : 8 }
{ "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in-stock" : false, "rating" : null }
{ "_id" : 5, "make" : "Ibanez", "description" : "Well-crafted guitars used by many professional guitarists.", "establishedYear" : 1957, "in-stock" : true, "rating" : 7 }

Observação

Por padrão, o operador regex não pode ser executado em um campo analisado. Você pode permitir que ele seja executado em um campo analisado definindo a opção allowAnalyzedField como "true", da seguinte forma:

var result = guitarsCollection.Aggregate()
 .Search(Builders<Guitar>.Search.Regex(g => g.Make, regex, true))
 .ToList();

Definir a opção allowAnalyzedField como verdadeiro pode levar a resultados de pesquisa inesperados. Para saber mais, consulte Comportamento regex.

Para saber mais sobre o operador regex , consulte o guia regex Atlas.

Espanha

Utilize o método Span para pesquisar correspondências de pesquisa de texto dentro de regiões de um campo. Você pode usar este método para encontrar strings próximas umas das outras com graus de precisão especificados.

Observação

O operador span é mais intensivo em termos de computação do que os outros operadores porque as queries devem manter o controle das informações de posição.

O exemplo a seguir pesquisa na coleção guitars os documentos em que o valor do campo description contém as strings "guitars" e "quality" dentro de uma palavra de cada.

var searchTerms = new[]
{
     Builders<Guitar>.SearchSpan.Term(g => g.Description, "guitars"),
     Builders<Guitar>.SearchSpan.Term(g => g.Description, "quality")
 };
var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Span(Builders<Guitar>.SearchSpan.Near(searchTerms, 1)))
    .ToList();

A pesquisa retorna o seguinte documento:

{ "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in-stock" : false, "rating" : null }

Embora o documento com _id: 3 contenha as strings "guitarras" e "qualidade", elas são separadas por mais de uma palavra, de modo que a pesquisa omite este documento dos resultados.

Para saber mais sobre o operador span , consulte o guia do Atlas de extensão .

Text

Use o método Text para pesquisar uma determinada string ou array de strings em um documento. Se houver vários termos em uma determinada string, o Atlas Search também procurará uma correspondência para cada termo na string separadamente.

O exemplo a seguir pesquisa a coleção guitars em busca de documentos nos quais o valor do campo description contém a string "usada por profissionais".

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Text(g => g.Description, "used by professional"))
    .ToList();

A pesquisa retorna o seguinte documento:

{ "_id" : 5, "make" : "Ibanez", "description" : "Well-crafted guitars used by many professional guitarists.", "establishedYear" : 1957, "in-stock" : true, "rating" : 7 }

Dica

Se a string de pesquisa contiver vários termos, o método também buscará uma correspondência para cada termo na string separadamente.

Para saber mais sobre o operador text, consulte o guia texto do Atlas.

Curinga

Use o método Wildcard para pesquisar documentos usando caracteres especiais em sua sequência de pesquisa que podem corresponder a qualquer caractere. Você pode usar os seguintes caracteres em sua pesquisa:

Personagem	Descrição
`?`	Corresponde a qualquer caractere único
`*`	Corresponde a 0 ou mais caracteres
`\`	Caractere de escape

O exemplo a seguir procura documentos nos quais o valor do campo make contém a string "Strand" seguida por qualquer outro caractere.

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Wildcard(g => g.Make, "Strand*"))
    .ToList();

A pesquisa retorna o seguinte documento:

{ "_id" : 6, "make" : "Strandberg", "description" : "Modern guitars known for their headless models.", "establishedYear" : 1982, "in-stock" : false, "rating" : null }

Observação

Por padrão, o operador wildcard não pode ser executado em um campo analisado. Você pode permitir que ele seja executado em um campo analisado definindo a opção allowAnalyzedField como "true", da seguinte forma:

var result =  guitarsCollection.Aggregate()
 .Search(Builders<Guitar>.Search.Wildcard(g => g.Make, "Strand*", true))
 .ToList();

Definir a opção allowAnalyzedField como verdadeira pode gerar resultados de pesquisa inesperados. Para saber mais, consulte Comportamento curinga.

Para saber mais sobre o operador wildcard, consulte o guia do Atlas de curingas.

Voltar

Operações com construtores

Stable API

Atlas Search.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Visão geral

Observação

Disponível apenas no Atlas para MongoDB v4.2 e posterior

Observação

criar um índice do atlas search

Atlas Search Operators

Observação

Autocompletar

composto

Iguais

Existe

GeoShape

Observação

GeoWithin

Observação

MoreLikeThis

Aproximar

Frase

QueryString

faixa

expressão regular

Observação

Espanha

Observação

Text

Dica

Curinga

Observação

Atlas Search