atlas-search.txt

.. _csharp-atlas-search:

============
Atlas Search
============

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: .NET, operators, aggregation, pipeline, atlas, code example

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

In this guide you can learn how to use the ``Search`` builder to build a ``$search``
aggregation pipeline stage with the {+driver-long+}.

To learn more about the ``$search`` pipeline stage, see :manual:`$search
</reference/operator/aggregation/search/>`.

.. note:: Only Available on Atlas for MongoDB v4.2 and Later

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

The examples in this guide use the following documents in a collection called
``guitars``:

.. code-block:: text
 
   { "_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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-guitar-class
   :end-before: // end-guitar-class
   :language: csharp
   :dedent:

.. 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 :ref:`csharp-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
:atlas:`Create an Atlas Search Index </atlas-search/create-index>` Atlas guide.

.. _csharp-atlas-search-operators:

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 :atlas:`Operators and Collectors
</atlas-search/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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-autocomplete-search
   :end-before: // end-autocomplete-search
   :language: csharp
   :dedent:

.. 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:

.. code-block:: text

    { "_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 :atlas:`autocomplete </atlas-search/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

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-compound-search
   :end-before: // end-compound-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

   { "_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 :atlas:`compound </atlas-search/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
   :atlas:`Define the Index for the embeddedDocument Type
   </atlas-search/field-types/embedded-documents-type/#define-the-index-for-the-fts-field-type-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:

.. code-block:: json

   { "_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"``:

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-embedded-search
   :end-before: // end-embedded-search
   :language: csharp
   :dedent:

The search returns the following document:

.. code-block:: text

   { "_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
:atlas:`embeddedDocument </atlas-search/embedded-document/>` 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``.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-equals-search
   :end-before: // end-equals-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

   { "_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 :atlas:`equals </atlas-search/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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-exists-search
   :end-before: // end-exists-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

   { "_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 :atlas:`exists </atlas-search/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 :atlas:`SEARCH_META Aggregation Variable </atlas-search/facet/#std-label-fts-facet-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``.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-facet-search
   :end-before: // end-facet-search
   :language: csharp
   :dedent:

The search returns the following result:

.. code-block:: none

   4

To learn more about the ``facet`` collector, see the :atlas:`facet </atlas-search/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.

.. include:: /includes/atlas-search-support-note.rst

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

.. code-block:: json
 
   { "_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:

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-geoshape-search
   :end-before: // end-geoshape-search
   :language: csharp
   :dedent:

The search returns the following document:

.. code-block:: text

   { "_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 :atlas:`geoShape </atlas-search/geoShape>` 
Atlas guide.

GeoWithin
~~~~~~~~~

Use the ``GeoWithin()`` method to search for documents in which the coordinates of
their specified :manual:`GeoJSON </reference/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.

.. include:: /includes/atlas-search-support-note.rst

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

.. code-block:: json
 
   { "_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: 

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-geowithin-search
   :end-before: // end-geowithin-search
   :language: csharp
   :dedent:

The search returns the following document:

.. code-block:: text

   { "_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 :atlas:`geoWithin </atlas-search/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"``.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: start-in-search
   :end-before: end-in-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

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

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-morelikethis-search
   :end-before: // end-morelikethis-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

   { "_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 :atlas:`moreLikeThis </atlas-search/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``.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-near-search
   :end-before: // end-near-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

   { "_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 :atlas:`near </atlas-search/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."

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-phrase-search
   :end-before: // end-phrase-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

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

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-multiphrase-search
   :end-before: // end-multiphrase-search
   :language: csharp
   :dedent:

This search returns the following documents:

.. code-block:: text

   { "_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 :atlas:`phrase </atlas-search/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"

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-querystring-search
   :end-before: // end-querystring-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: text

   { "_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 :atlas:`queryString </atlas-search/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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-range-search
   :end-before: // end-range-search
   :language: csharp
   :dedent:

The search returns the following results:

.. code-block:: text

   { "_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 :atlas:`token index
</atlas-search/field-types/token-type/>` 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:

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-range-string
   :end-before: // end-range-string
   :language: csharp
   :dedent:

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 :wikipedia:`lexicographic order
<Lexicographic_order>`. 

The search returns the following results:

.. code-block:: text

   { "_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 :atlas:`range </atlas-search/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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-regex-search
   :end-before: // end-regex-search
   :language: csharp
   :dedent:

The search returns the following results:

.. code-block:: text

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

   .. code-block:: csharp

      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 :atlas:`regex Behavior
   </atlas-search/regex/#behavior>`.

To learn more about the ``regex`` operator, see the :atlas:`regex </atlas-search/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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-span-search
   :end-before: // end-span-search
   :language: csharp
   :dedent:

The search returns the following document:

.. code-block:: text

   { "_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 :atlas:`span </atlas-search/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".

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-text-search
   :end-before: // end-text-search
   :language: csharp
   :dedent:

The search returns the following document:

.. code-block:: text

   { "_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 :atlas:`text </atlas-search/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:

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - 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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-wildcard-search
   :end-before: // end-wildcard-search
   :language: csharp
   :dedent:

The search returns the following document:

.. code-block:: text

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

   .. code-block:: csharp

      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 :atlas:`wildcard Behavior
   </atlas-search/wildcard/#behavior>`.

To learn more about the ``wildcard`` operator, see the :atlas:`wildcard </atlas-search/wildcard>` 
Atlas guide.

Search Multiple Fields
----------------------

The ``path`` parameter is used by the Atlas Search
:atlas:`operators </atlas-search/query-syntax>` to specify the field or fields
to be searched. To learn more about what the ``path`` parameter may contain, see the :atlas:`Construct a Query Path </atlas-search/path-construction>` 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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-multiple-field-search
   :end-before: // end-multiple-field-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: json

   { "_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 :atlas:`score </atlas-search/scoring>` 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.

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-score-search
   :end-before: // end-score-search
   :language: csharp
   :dedent:

The search returns the following documents:

.. code-block:: json

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

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Property
     - Description

   * - ``CountOptions`` 
     - | The options for counting the search results.

       | **Data type**: `SearchCountOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.SearchCountOptions.html>`__
       | **Default**: ``null``

   * - ``Highlight`` 
     - | The options for displaying search terms in their original context.

       | **Data type**: `SearchHighlightOptions<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.SearchHighlightOptions-1.html>`__
       | **Default**: ``null``

   * - ``IndexName`` 
     - | The index to use for the search.

       | **Data type**: {+string-data-type+}
       | **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**: {+bool-data-type+}
       | **Default**: ``false``

   * - ``ScoreDetails`` 
     - | A flag that specifies whether to return detailed information about the
         score for each document in the results.

       | **Data type**: {+bool-data-type+}
       | **Default**: ``false``

   * - ``SearchAfter`` 
     - | The starting point for pagination. When set, the search retrieves documents
         starting immediately after the specified reference point.

       | **Data type**: {+string-data-type+}
       | **Default**: ``null``

   * - ``SearchBefore`` 
     - | The end point for pagination. When set, the search retrieves documents
         starting immediately before the specified reference point.

       | **Data type**: {+string-data-type+}
       | **Default**: ``null``

   * - ``Sort`` 
     - | The sorting criteria to apply to the results.

       | **Data type**: `SortDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinition-1.html>`__
       | **Default**: ``null``

   * - ``Tracking`` 
     - | The options for tracking search terms.

       | **Data type**: `SearchTrackingOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Search.SearchTrackingOptions.html>`__
       | **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

.. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs
   :start-after: // start-pagination-options
   :end-before: // end-pagination-options
   :language: csharp
   :dedent:

The search returns the following document:

.. code-block:: json

   { "_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 :atlas:`Paginate the Results </atlas-search/paginate-results/>` 
   in the Atlas documentation.