Atlas Search

Overview

In this guide you can learn how to use the Search builder to build a $search aggregation pipeline stage with the MongoDB .NET/C# Driver.

To learn more about the $search pipeline stage, see $search.

Note

Only Available on Atlas for MongoDB v4.2 and Later

The $search aggregation-pipeline operator is available only for collections hosted on MongoDB Atlas clusters running MongoDB v4.2 or later that are covered by an Atlas search index. To learn more about the required setup and the functionality of this operator, see the Atlas Search documentation.

The examples in this guide use the following documents in a collection called 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 }

The following Guitar class models the documents in this 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; }
}

Note

The documents in the guitars collection use the camel-case naming convention. The examples in this guide use a ConventionPack to deserialize the fields in the collection into Pascal case and map them to the properties in the Guitar class.

To learn more about custom serialization, see Custom Serialization.

Create an Atlas Search Index

Before you can perform a search on an Atlas collection, you must first create an Atlas Search index on the collection. An Atlas Search index is a data structure that categorizes data in a searchable format.

To learn how to create an Atlas Search Index see the Create an Atlas Search Index Atlas guide.

Atlas Search Operators and Collectors

The Search class contains methods you can use to perform $search operations. For a full list of available $search operators and collectors, see the Operators and Collectors Atlas guide.

Autocomplete

Use the Autocomplete() method to search for a word or phrase that contains a sequence of characters from an incomplete input string.

The following example performs an autocomplete query on the make field for text that starts with the string "Gib".

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

Note

Index for Autocomplete Queries

You must create an Atlas Search index that supports autocompletion to successfully perform autocomplete queries. To learn more, see How to Index Fields for Autocompletion in the Atlas documentation.

After you create the Atlas Search index, you must pass the index name to the Autocomplete() method, as shown in the preceding code.

The search returns the following document:

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

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

Compound

Use the Compound() method to combine two or more operators into a single search.

The following example searches the guitars collection for any documents that match all of the following criteria:

The rating field exists on the document
The in_stock field is not false
The establishedYear field has a value greater than 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();

The search returns the following documents:

{ "_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 }

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

EmbeddedDocument

Use the EmbeddedDocument() method to perform search operations on documents within a field's array value.

Note

To search on embedded documents, you must create an embeddedDocument index on the array field.

To learn how to define an embeddedDocument index, see Define the Index for the embeddedDocument Type in the Atlas documentation.

Consider that some documents in the guitars collection have added a productDetails field that holds an array of product detail objects:

{ "_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 }

After creating an embeddedDocument index on the productDetails field, you can perform Atlas search operations on documents in that field. The following example performs a text search on the productDetails array fields and returns any documents with a serial field value of "YZ5678":

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

The search returns the following document:

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

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

Equals

Use the Equals() method to check whether a field matches a specified value.

The following example searches the guitars collection for any documents in which the value of the in_stock field is true.

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

The search returns the following documents:

{ "_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 }

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

Exists

Use the Exists() method to search for documents in which a specified indexed field name exists. If the specified field exists but is not indexed, the document is not included with the result set.

The following example searches the guitars collection for any documents in which the rating field exists.

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

The search returns the following documents:

{ "_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 }

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

Facet

Use the Facet() method to group results by values or ranges in the specified faceted fields and return the count for each of those groups.

You can use the Facet() method with both the $search and $searchMeta stages. MongoDB recommends using facet with the $searchMeta stage to retrieve metadata results only for the query. To retrieve metadata results and query results using the $search stage, you must use the $$SEARCH_META aggregation variable. To learn more about this variable, see the SEARCH_META Aggregation Variable Atlas guide.

The following limitations apply:

You can run facet queries on a single field only. You can't run facet queries on groups of fields.
You can run facet queries over sharded collections on clusters running MongoDB v6.0 only.

The following example searches the guitars collection for any documents in which the value of the in_stock field is true. The query uses the Facet() method to process the input documents, with a maximum number of 100 facet categories to return in the results. The query returns the total count of documents in which the value of in_stock is 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();

The search returns the following result:

To learn more about the facet collector, see the facet Atlas guide.

GeoShape

Use the GeoShape() method to search for documents in relation to a given geometry. When specifying the coordinates to search, longitude must be specified first, followed by latitude. Longitude values can be between -180 and 180, inclusive. Latitude values can be between -90 and 90, inclusive.

Note

Atlas Search does not support the following:

Non-default coordinate reference system (CRS)
Planar XY coordinate system (2 dimensional)
Coordinate pairs Point notation (pointFieldName: [12, 34])

Consider some documents in the guitars collection have added an in_stock_location field. The changed documents in the collection now look as follows:

{ "_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 }

The following example searches for all documents in which the coordinates in the in_stock_location field intersect with a specified polygon:

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();

The search returns the following document:

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

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

GeoWithin

Use the GeoWithin() method to search for documents in which the coordinates of their specified GeoJSON field are within a given geometry. You can search for points that are within a:

Circle
Bounding box
Polygon

When specifying the coordinates to search, longitude must be specified first, followed by latitude. Longitude values can be between -180 and 180, inclusive. Latitude values can be between -90 and 90, inclusive.

Note

Atlas Search does not support the following:

Non-default coordinate reference system (CRS)
Planar XY coordinate system (2 dimensional)
Coordinate pairs Point notation (pointFieldName: [12, 34])

Consider some documents in the guitars collection have added an in_stock_location field. The changed documents in the collection now look as follows:

{ "_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 }

The following example searches for all documents in which the coordinates in the in_stock_location field falls within a specified polygon:

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();

The search returns the following document:

{ "_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 }

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

In

Use the In() method to search for documents with field values that match a list of specified values.

The following example searches the guitars collection for documents that have a make field value of either "Fender" or "Gibson".

var result = guitarsCollection.Aggregate()
    .Search(Builders<Guitar>.Search.In(g => g.Make, ["Fender", "Gibson"]))
    .ToList();

The search returns the following documents:

{ "_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 the MoreLikeThis() method to search for documents that are similar to an input document.

The following example searches the guitars collection for documents that are similar to an object in which the value of the Description field is "high quality."

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

The search returns the following documents:

{ "_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 }

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

Near

Use the Near() method to search for documents in which a specified field is near a given value. You can perform the search on:

A number field
A date field
A geographic point

The following example searches the guitars collection for documents in which the value of the rating field is near 9. The documents are returned in order based on how close the value is to the number 9.

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

The search returns the following documents:

{ "_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.

Phrase

Use the Phrase() method to search for documents in which a specified field contains an input string.

The following example searches the guitars collection for documents in which the description field contains the phrase "classic guitars."

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

The search returns the following documents:

{ "_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 }

You can also search the collection for documents that match multiple separate phrases as follows:

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

This search returns the following documents:

{ "_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 }

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

QueryString

Use the QueryString() method to search for documents using a string with the following operators and delimiters:

AND
OR
NOT
()

The following example searches the guitars collection for documents in which the value of the description field matches each of the following criteria:

Contains the string "classic" or the string "quality"
Does not contain the string "custom"

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

The search returns the following documents:

{ "_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 }

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

Range

Use the Range() method to search for documents in which the value of a specified field falls within a given numeric, date, or string range.

The following example searches the guitars collection for all documents with an establishedYear value greater than 1980 and less than 2020.

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

The search returns the following results:

{ "_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 }

To search for documents in which the value of a specified field is within a range of strings, you must first create a token index on the field. After you create the index, you can search for documents based on a range of strings as shown in the following example:

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

The preceding example searches for any documents in which the string value of the make field is greater than or equal to "Fender" and less than or equal to "Kiesel". The driver compares the string values in lexicographic order.

The search returns the following results:

{ "_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 }

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

Regex

Use the Regex() method to search for documents using a regular expression.

The following example searches the guitars collection for documents in which the value of the make field contains exactly six letters.

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

The search returns the following results:

{ "_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 }

Note

By default the regex operator cannot run on an analyzed field. You can allow it to run on an analyzed field by setting allowAnalyzedField option to true, as follows:

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

Setting the allowAnalyzedField option to true may lead to unexpected search results. To learn more, see regex Behavior.

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

Span

Use the Span() method to search for text search matches within regions of a field. You can use this method to find strings which are near each other to specified degrees of precision.

Note

The span operator is more computationally intensive than other operators because queries must keep track of positional information.

The following example searches the guitars collection for documents in which the value of the description field contains the strings "guitars" and "quality" within one word of each other.

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();

The search returns the following document:

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

Although the document with _id: 3 contains the strings "guitars" and "quality", they are separated by more than one word, so the search omits this document from the results.

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

Text

Use the Text() method to search a document for a given string or array of strings. If there are multiple terms in a given string, Atlas Search also looks for a match for each term in the string separately.

The following example searches the guitars collection for documents in which the value of the description field contains the string "used by professionals".

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

The search returns the following document:

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

Tip

If your search string contains multiple terms, the method also looks for a match for each term in the string separately.

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

Wildcard

Use the Wildcard() method to search for documents using special characters in your search string that can match any character. You can use the following characters in your search:

Character	Description
`?`	Matches any single character
`*`	Matches 0 or more characters
`\`	Escape character

The following example searches for documents in which the value of the make field contains the string "Strand" followed by any other characters.

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

The search returns the following document:

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

Note

By default the wildcard operator cannot run on an analyzed field. You can allow it to run on an analyzed field by setting allowAnalyzedField option to true, as follows:

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

Setting the allowAnalyzedField option to true may lead to unexpected search results. To learn more, see wildcard Behavior.

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

Search Multiple Fields

The path parameter is used by the Atlas Search operators to specify the field or fields to be searched. To learn more about what the path parameter may contain, see the Construct a Query Path guide.

Note

Not all operators can use all the different types of paths. See the documentation for each individual operator for details on what types of path it supports.

To search multiple indexed fields, use the Multi() method and pass in your fields. Documents which match on any of the specified fields are included in the result set.

The following example searches for the string classic in either the make or the description field.

var result = guitarsCollection.Aggregate().Search(
    Builders<Guitar>.Search.Phrase(Builders<Guitar>.SearchPath
    .Multi(g => g.Description, g => g.Make), "classic"), indexName: "guitarmulti")
    .ToList();

The search returns the following documents:

{ "_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}

Score Documents

Every document returned by an Atlas Search query is assigned a score based on relevance, and the documents included in a result set are returned in order from highest score to lowest. To learn more about how scores are assigned, see the score Atlas guide.

The score assigned to a returned document is part of the document's metadata. You can include each returned document's score along with the result set by using a $project stage in your aggregation pipeline.

The following example searches the guitars collection for documents in which the value of the make field contains exactly six letters and uses a $project stage to add a field named score to the returned documents.

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();

The search returns the following documents:

{ "_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 }

Modify Atlas Search Behavior

You can modify the behavior of the Search() method by passing a SearchOptions object as a parameter.

The SearchOptions class contains the following properties:

Property	Description
`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`

SearchAfter Example

The following example paginates the results of an Atlas Search operation by performing the following actions:

Defines a projection that uses the MetaSearchSequenceToken() builder method, which specifies a PaginationToken to contain the point of reference
Creates a SearchOptions instance and sets the index and sort criteria to use
Runs an initial search to find documents that have a description field value containing the text "classic", applying the projection and options to the operation
Sets the SearchAfter property of the same SearchOptions instance to instruct the next search to begin after the base search's first result
Runs another search operation that has the same matching criteria and applies the search options to paginate the results

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)
    .Project<Guitar>(projection)
    .ToList();

The search returns the following document:

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

Tip

To learn more about Atlas Search pagination, see Paginate the Results in the Atlas documentation.

Back

Operations with Builders

Atlas Vector Search