Atlas Search

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 o estágio de pipeline $search, 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 string Description { get; set; }
    public int EstablishedYear { get; set; }
    [BsonElement("in_stock")]
    public bool InStock { get; set; }
    [BsonElement("in_stock_location")]
    public Location InStockLocation { get; set; }
    public int? Rating { get; set; }
    public double Score {get; set;}
    [BsonElement("paginationToken")]
    public string PaginationToken { 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.

Operadores e coletores do Atlas Search

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

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 a seguir executa uma query de preenchimento automático no campo make para texto que começa com a string "Gib".

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

Observação

Índice para queries de preenchimento automático

Você deve criar um índice do Atlas Search que ofereça suporte ao preenchimento automático para realizar consultas de preenchimento automático com sucesso. Para saber mais, consulte Como indexar campos para preenchimento automático na documentação do Atlas.

Depois de criar o índice do Atlas Search, você deve passar o nome do índice para o método Autocomplete(), conforme mostrado no código anterior.

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 a seguir 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.

documento incorporado

Use o método EmbeddedDocument() para realizar operações de pesquisa em documentos dentro do valor da array de um campo.

Observação

Para usar o Atlas Search em documentos incorporados, você deve criar um índice embeddedDocument no campo de array.

Para saber como definir um índice embeddedDocument, consulte Definir o índice para o tipo embeddedDocument na documentação do Atlas.

Considere que alguns documentos na coleção guitars adicionaram um campo productDetails que contém uma array de objetos de detalhes do produto:

{ "_id": 1, "make": "Fender", "description": "...", "establishedYear": 1946, "in_stock": true, "rating": 9, "productDetails": [{"product_id": 1234, "serial": "YZ5678"}] }
{ "_id": 2, "make": "Gibson", "description": "...", "establishedYear": 1902, "in_stock": true, "rating": 8 }
{ "_id": 3, "make": "PRS", "description": "...", "establishedYear": 1985, "in_stock": true, "rating": 9, "productDetails": [{"product_id": 9870, "serial": "AB5555"}] }
{ "_id": 4, "make": "Kiesel", "description": "...", "establishedYear": 2015, "in_stock": false }
{ "_id": 5, "make": "Ibanez", "description": "...", "establishedYear": 1957, "in_stock": true, "rating": 7, "productDetails": [{"product_id": 5432, "serial": "ZZ1234"}] }
{ "_id": 6, "make": "Strandberg", "description": "...", "establishedYear": 1982, "in_stock": false }

Após criar um índice embeddedDocument no campo productDetails, você pode executar operações de Atlas search em documentos nesse campo. O exemplo a seguir executa uma pesquisa de texto nos campos da matriz productDetails e retorna todos os documentos com um valor de campo serial de "YZ5678":

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.EmbeddedDocument(
        g => g.ProductDetails,
        Builders<ProductDetails>.Search.Text(p => p.Serial, "YZ5678")
    )).ToList();
return result;

A pesquisa retorna o seguinte documento:

{ "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "rating" : 9, "productDetails" : [{ "product_id" : 1234, "serial" : "YZ5678" }] }

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

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.

Facet

Use o método Facet() para agrupar resultados por valores ou intervalos nos campos facetados especificados e retornar a contagem para cada um desses grupos.

Você pode usar o método Facet() com os estágios $search e $searchMeta. O MongoDB recomenda usar o faceta com o estágio $searchMeta para recuperar resultados de metadados somente para a query. Para recuperar resultados de metadados e queries usando o estágio $search, use a variável de agregação $$SEARCH_META. Para saber mais sobre essa variável, consulte o guia Atlas de variável de agregação SEARCH_META.

Aplicam-se as seguintes limitações:

Você pode executar queries de facets somente em um único campo. Não é possível executar queries de atributos em grupos de campos.
Você pode executar queries de faceta em collections fragmentadas em clusters que executam apenas o MongoDB v6.0.

O exemplo a seguir pesquisa a coleção guitars para quaisquer documentos nos quais o valor do campo in_stock é true. A consulta utiliza o método Facet() para processar os documentos de entrada, com um número máximo de 100 categorias de facetas a serem retornadas nos resultados. A consulta retorna o total de documentos em que o valor de in_stock é true.

var result = guitarsCollection.Aggregate()
    .SearchMeta(
    	Builders<Guitar>.Search.Facet(
    	          Builders<Guitar>.Search.Equals(g => g.InStock, true),
    	          Builders<Guitar>.SearchFacet.String("string", g => g.Make, 100)), 
        indexName: "guitarfacetsearch")
     .Single()
     .Facet["string"].Buckets.Count();

A pesquisa retorna o seguinte resultado:

Para saber mais sobre o coletor facet, consulte o guia do Atlas facet.

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.

In

Use o método In() para pesquisar documentos com valores de campo que correspondam a uma lista de valores especificados.

O exemplo a seguir pesquisa a coleção guitars em busca de documentos que tenham um valor de campo make de "Fender" ou "Gibson".

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.In(g => g.Make, ["Fender", "Gibson"]))
    .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 }

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, de data ou de string.

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 buscar documentos em que o valor de um campo especificado esteja dentro de um intervalo de strings, é necessário primeiro criar um índice de token no campo. Depois de criar o índice, você pode pesquisar documentos com base em uma variedade de strings, conforme mostrado no exemplo a seguir:

var result = guitarsCollection.Aggregate()
     .Search(Builders<Guitar>.Search
     .Range(g => g.Make, SearchRangeV2Builder.Gte("Fender").Lte("Kiesel")))
     .ToList();

O exemplo anterior pesquisa qualquer documento em que o valor da string do campo make seja maior ou igual a "Fender" e menor ou igual a "Kiesel". O driver compara os valores da string em ordem lexicográfica.

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 }

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.

pesquisar vários campos

O parâmetro path é usado pelos operadores do Atlas Search para especificar o campo ou campos a serem pesquisados. Para aprender mais sobre o que o parâmetro path pode conter, consulte o guia Construção de um Caminho de query.

Observação

Nem todos os operadores podem usar todos os diferentes tipos de caminhos. Consulte a documentação de cada operador individual para obter detalhes sobre os tipos de caminho suportados.

Para pesquisa de múltiplos campos indexados, utilize o método Multi() e passe seus campos. Os documentos que correspondem a qualquer um dos campos especificados são incluídos no conjunto de resultados.

O exemplo a seguir pesquisa a string classic no campo make ou no campo description.

var result = guitarsCollection.Aggregate().Search(
    Builders<Guitar>.Search.Phrase(Builders<Guitar>.SearchPath
    .Multi(g => g.Description, g => g.Make), "classic"), indexName: "guitarmulti")
    .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}

Documentos de pontuação

A cada documento retornado por uma query da Atlas Search é atribuída uma pontuação com base na relevância, e os documentos incluídos em um conjunto de resultados são retornados na ordem da pontuação mais alta para a mais baixa. Para aprender mais sobre como as pontuações são atribuídas, consulte o guia do Atlas pontuação.

A pontuação atribuída a um documento retornado faz parte dos metadados do documento. Você pode incluir a pontuação de cada documento retornado junto com o conjunto de resultados usando uma etapa $project em sua agregação pipeline.

O exemplo a seguir pesquisa a coleção guitars em busca de documentos nos quais o valor do campo make contém exatamente seis letras e usa um estágio $project para adicionar um campo chamado score aos documentos retornados.

var regex = "[A-Za-z]{6}";
var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.Regex(g => g.Make, regex, allowAnalyzedField: true), indexName: "guitarscore")
    .Project<Guitar>(Builders<Guitar>.Projection
    .Include("Id")
    .Include("Make")
    .Include("Description")
    .MetaSearchScore(g => g.Score))
    .ToList();

A pesquisa retorna os seguintes documentos:

{ "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 0, "in_stock" : false, "rating" : null, "score" : 1.0 }
{ "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 0, "in_stock" : false, "rating" : null, "score" : 1.0 }
{ "_id" : 5, "make" : "Ibanez", "description" : "Well-crafted guitars used by many professional guitarists.", "establishedYear" : 0, "in_stock" : false, "rating" : null, "score" : 1.0 }
{ "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 0, "in_stock" : false, "rating" : null, "score" : 1.0 }

Modificar o comportamento do Atlas Search

Você pode modificar o comportamento do método Search() passando um objeto SearchOptions como parâmetro.

A classe SearchOptions contém as seguintes propriedades:

Propriedade	Descrição
`CountOptions`	The options for counting the search results. Data type: SearchCountOptions Default: `null`
`Highlight`	The options for displaying search terms in their original context. Data type: SearchHighlightOptions<TDocument> Default: `null`
`IndexName`	The index to use for the search. Data type: `string` Default: `null`
`ReturnStoredSource`	A flag that specifies whether to perform a full document lookup on the database or to return only stored source fields directly from Atlas Search. Data type: `boolean` Default: `false`
`ScoreDetails`	A flag that specifies whether to return detailed information about the score for each document in the results. Data type: `boolean` Default: `false`
`SearchAfter`	The starting point for pagination. When set, the search retrieves documents starting immediately after the specified reference point. Data type: `string` Default: `null`
`SearchBefore`	The end point for pagination. When set, the search retrieves documents starting immediately before the specified reference point. Data type: `string` Default: `null`
`Sort`	The sorting criteria to apply to the results. Data type: SortDefinition<TDocument> Default: `null`
`Tracking`	The options for tracking search terms. Data type: SearchTrackingOptions Default: `null`

Exemplo de SearchAfter

O exemplo seguinte pagina os resultados de uma operação do Atlas Search executando as seguintes ações:

Define uma projeção que utiliza o método construtor MetaSearchSequenceToken(), que especifica um PaginationToken para conter o ponto de referência
Cria uma instância SearchOptions e define o índice e os critérios de classificação a serem utilizados.
Executa uma pesquisa inicial para encontrar documentos que possuam um valor no campo description que contenha o texto "classic", aplicando a projeção e as opções à operação
Configura a propriedade SearchAfter da mesma instância SearchOptions para instruir a próxima pesquisa a iniciar após o primeiro resultado da pesquisa base
Executa outra operação de pesquisa que possui os mesmos critérios de correspondência e aplica as opções de pesquisa para paginar os resultados

var projection = Builders<Guitar>.Projection
    .Include(x => x.Make)
    .MetaSearchSequenceToken(x => x.PaginationToken);
var searchDefinition = Builders<Guitar>.Search.Text(g => g.Description, "classic");
var searchOptions = new SearchOptions<Guitar>
{ IndexName = "default", Sort = Builders<Guitar>.Sort.Ascending(g => g.Id) };
// Runs the base search operation
var baseSearchResults = guitarsCollection.Aggregate()
    .Search(searchDefinition, searchOptions)
    .Project<Guitar>(projection)
    .ToList();
// Sets the starting point for the next search
searchOptions.SearchAfter = baseSearchResults[0].PaginationToken;
var result = guitarsCollection.Aggregate()
    .Search(searchDefinition, searchOptions)
    .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 }

Dica

Para aprender mais sobre a paginação do Atlas Search, veja Paginar os resultados na documentação do Atlas.

Voltar

Executar um comando de banco de dados

Atlas Vector Search