Atlas Search
On this page
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 List<string> Models { get; set; } public int EstablishedYear { get; set; } [ ] public bool InStock { get; set; } public int? Rating { 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
The Search
class contains methods you can use to perform $search
operations. For a full list of available $search
operators, 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 search on the guitars
collection using the string "Gib" in the make
field.
var result = guitarsCollection.Aggregate() .Search(Builders<Guitar>.Search.Autocomplete(g => g.Make, "Gib"), indexName: "guitarmakes") .ToList();
Note
If the field you are searching on is indexed by a search index, you must pass the index name to the Autocomplete
call. If a search index does not exist, the default index is used.
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 documentThe
in_stock
field is notfalse
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.
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.
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 or date 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 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.