Merge branch 'docsp-45382-comp-cvg' into docsp-49786-meta-operator

Author: mongoKart

config/intersphinx.yaml

@@ -1,4 +1,4 @@
-# Weirdly, giza wants a non-empty list of two or more, so we have to include extraneous/unused one --hence the python
+# Weirdly, giza wants a non-empty list of two or more, so we must include extraneous/unused one --hence the python
 name: python
 url: https://docs.python.org/2/
 path: python2.inv

snooty.toml

@@ -44,3 +44,4 @@ not-available = "N/A"
 analyzer = "MongoDB C# Analyzer"
 analyzer-short = "C# Analyzer"
 query-api = "MongoDB Query API"
+avs = "Atlas Vector Search"

source/aggregation.txt

@@ -38,6 +38,12 @@ more stages, and this pipeline transforms the documents into an aggregated resul
 To learn more about the aggregation stages supported by the {+driver-short+}, see
 :ref:`Aggregation Stages <csharp-aggregation-stages>`.
 
+.. sharedinclude:: dbx/agg-tutorials-manual-tip.rst
+
+   .. replacement:: language
+
+      :guilabel:`{+language+}`
+
 Analogy
 ~~~~~~~
 
@@ -110,4 +116,4 @@ To view a full list of expression operators, see
 
 To learn about explaining MongoDB aggregation operations, see
 :manual:`Explain Results </reference/explain-results/>` and
-:manual:`Query Plans </core/query-plans/>`.
+:manual:`Query Plans </core/query-plans/>`.

source/aggregation/stages.txt

@@ -170,6 +170,12 @@ to your pipeline.
        dimensions, or facets, in a single stage.
      - ``Facet()``
 
+   * - :manual:`$geoNear </reference/operator/aggregation/geoNear/>`
+     - Returns documents in order of nearest to farthest from a
+       specified point. This method adds a field to output documents
+       that contains the distance from the specified point.
+     - ``GeoNear()``
+
    * - :manual:`$graphLookup </reference/operator/aggregation/graphLookup/>`
      - Performs a recursive search on a collection. This method adds  
        a new array field to each output document that contains the traversal  
@@ -353,4 +359,5 @@ following API documentation:
 - `AggregateOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateOptions.html>`__
 - `EmptyPipelineDefinition<TDocument> <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.EmptyPipelineDefinition-1.-ctor.html>`__
 - `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__
-- `PipelineDefinitionBuilder.AppendStage() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.AppendStage.html>`__
+- `PipelineDefinitionBuilder.AppendStage()
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.AppendStage.html>`__

source/atlas-search.txt

@@ -122,7 +122,7 @@ 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:
+that match all the following criteria:
 
 - The ``rating`` field exists on the document
 - The ``in_stock`` field is not ``false``

source/atlas-vector-search.txt

@@ -1,46 +1,180 @@
 .. _csharp-atlas-vector-search:
 
-===================
-Atlas Vector Search
-===================
+================================
+Run an Atlas Vector Search Query
+================================
 
 .. facet::
    :name: genre
    :values: reference
 
 .. meta::
-   :keywords: semantic
+   :keywords: .NET, search, semantic, AI, RAG
 
 .. contents:: On this page
    :local:
    :backlinks: none
    :depth: 2
    :class: singlecol
 
-Sample Class
-------------
+Overview
+--------
 
-The code examples in this guide demonstrate how you can use builders to
-create types to interact with documents in the sample collection ``plants.flowers``.
-Documents in this collection are modeled by the following ``Flower`` class:
+You can use {+avs+} to perform vector search on your data stored in
+Atlas. Vector search allows you to query your data based on semantic meaning
+rather than just keyword matches, which helps you retrieve more relevant search
+results. It enables your AI-powered applications to support use cases such as
+semantic search, hybrid search, and generative search, including
+Retrieval-Augmented Generation (RAG).
 
-.. literalinclude:: /includes/fundamentals/code-examples/builders.cs
+By using Atlas as a vector database, you can seamlessly index vector data along
+with your other data in Atlas. This allows you to filter on fields in your
+collection and perform vector search queries against vector data. You can also
+combine vector search with full-text search queries to return the most relevant
+results for your use case. You can integrate {+avs+} with popular AI
+frameworks and services to easily implement vector search in your applications.
+
+To learn more about {+avs+}, see the :atlas:`{+avs+}
+</atlas-vector-search/vector-search-overview/>` guide in the MongoDB Atlas
+documentation.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``sample_mflix.embedded_movies`` collection
+in the ``sample_mflix`` database. To obtain the sample dataset for this collection,
+see :ref:`csharp-get-started`.
+
+The examples in this guide use the following sample class to model documents in the
+``sample_mflix.embedded_movies`` collection:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchQueryExample.cs
    :language: csharp
-   :dedent:
-   :start-after: start-model
-   :end-before: end-model
+   :start-after: start-sample-class
+   :end-before: end-sample-class
+
+.. _csharp-supported-vector-types:
 
-Each builder class takes a generic type parameter
-``TDocument`` which represents the type of document that you are working
-with. In this guide, the ``Flower`` class is the document type used in
-each builder class example.
+Supported Vector Embedding Types
+--------------------------------
 
-Perform an Atlas Vector Search
-------------------------------
+:atlas:`Vector embeddings
+</atlas-vector-search/vector-search-overview/#std-term-vector-embeddings>`
+are vectors you use to represent your data. These embeddings
+capture meaningful relationships in your data and enable tasks like semantic
+search and retrieval.
 
-You can use builders to create a ``$vectorSearch`` aggregation pipeline stage to perform an
-approximate nearest neighbor search on a vector in the specified field. Your collection *must*
-have a defined Atlas Vector Search index before you can perform a vector search on your data.
+The {+driver-short+} supports vector embeddings of several types. The following
+sections describe the supported vector embedding types.
+
+.. _csharp-vector-array-representation:
+
+Array Representations
+~~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} supports the following representations of the array
+type in vector embeddings:
+
+- ``BsonArray``
+- ``Memory``
+- ``ReadOnlyMemory``
+- ``float[]`` and ``double[]``
+
+The following example shows a class with properties of the preceding types:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
+   :language: csharp
+   :start-after: start-bson-arrays
+   :end-before: end-bson-arrays
+
+.. tip::
+
+   To learn more about using the ``Memory`` and ``ReadOnlyMemory``
+   types, see the :ref:`csharp-array-serialization` section of the
+   Serialization guide.
+
+.. _csharp-binary-vector-representation:
+
+Binary Vector Representations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} supports the following binary vector representations in
+vector embeddings:
+
+- ``BinaryVectorFloat32`` (not supported on big-endian architectures)
+- ``BinaryVectorInt8``
+- ``BinaryVectorPackedBit``
+- ``Memory<float>``, ``Memory<byte>``, ``Memory<sbyte>``
+- ``ReadOnlyMemory<float>``, ``ReadOnlyMemory<byte>``, ``ReadOnlyMemory<sbyte>``
+- ``float[]``, ``byte[]``, ``sbyte[]``
+
+.. note::
+
+   You must use the ``BinaryVector`` attribute when specifying binary vector
+   representations of the ``Memory<T>``, ``ReadOnlyMemory<T>``, or array
+   types.
+
+The following example shows a class with properties of the preceding types:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
+   :language: csharp
+   :start-after: start-binary-vectors
+   :end-before: end-binary-vectors
+
+Binary Vector Data Serialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can serialize ``Int8`` binary vector typed data as ``byte`` or ``sbyte``.
+You can also serialize ``Float32`` binary vector typed data as ``float``. The
+following example serializes ``Int8`` and ``Float32`` binary vector data:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
+   :language: csharp
+   :start-after: start-binary-int-float-serialize
+   :end-before: end-binary-int-float-serialize
+
+You can deserialize ``PackedBit`` vector data to a :ref:`binary vector
+represented <csharp-binary-vector-representation>` ``byte`` data type only if the
+vector data has a padding value of ``0``. If the vector data has a padding value not
+equal to ``0``, you can deserialize it only to a ``BsonVectorPackedBit``.
+
+Vector Search Query Example
+---------------------------
+
+You can perform a vector search query by calling the ``VectorSearch()`` method.
+To perform a vector search on a collection, you must first have a collection with a field that contains
+vector data and a vector search index that covers that field.
+
+To learn more about configuring a collection for vector search, see the :atlas:`{+avs+}
+</atlas-vector-search/vector-search-overview/>` guide in the MongoDB Atlas
+documentation.
+
+You can convert ``BinaryVectorFloat32``, ``BinaryVectorInt8``, and
+``BinaryVectorPackedBit`` data to the ``BsonBinaryData`` type to use in a vector
+search query by using the ``ToQueryVector()`` method. The following example
+converts ``BinaryVectorInt8`` into a ``BsonBinaryData`` object:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
+   :language: csharp
+   :start-after: start-to-query-vector
+   :end-before: end-to-query-vector
+
+You can specify your :ref:`array-represented
+<csharp-vector-array-representation>` vector data as an instance of the
+``QueryVector`` class to use in a vector search query. The following example 
+creates an array of ``ReadOnlyMemory<float>`` values as a ``QueryVector`` object
+to use in a vector search query:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
+   :language: csharp
+   :start-after: start-array-query-vector
+   :end-before: end-array-query-vector
+   
+Consider the ``embedded_movies`` collection in the ``sample_mflix`` database. You
+can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding``
+field of the documents in the collection.
+The following sections describe different methods for performing Atlas Vector Search operations
+on this collection.
 
 .. tip::
 
@@ -49,15 +183,20 @@ have a defined Atlas Vector Search index before you can perform a vector search
    :atlas:`Create an Atlas Vector Search Index </atlas-vector-search/create-index>` in the
    Atlas manual.
 
-Consider the ``embedded_movies`` collection in the ``sample_mflix`` database. You
-can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding``
-field of the documents in the collection.
+Aggregation Pipeline Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following example shows how to use builders to generate an aggregation pipeline to
-perform the following operations:
+This example performs the following steps to run an {+avs+} query on a collection that
+contains vector data and a vector search index on the ``PlotEmbedding`` field:
 
-- Performs a vector search on the Atlas Vector Search index of the ``plot_embedding`` field using vector embeddings for the string ``"time travel"``
-- Fetches the ``Title`` and ``Plot`` fields from documents found in the vector search
+1. Creates an array that contains the :ref:`array-represented
+   <csharp-vector-array-representation>` vector data to search for
+#. Specifies a ``VectorSearchOptions`` object that contains the name of the index
+   and the number of nearest neighbors to use during the search
+#. Creates an aggregation pipeline that uses the ``VectorSearch()`` stage to
+   perform the vector search query and a ``Project()`` stage to display only
+   the ``Title``, ``Plot``, and ``Score`` fields
+#. Prints the results of the query
 
 .. code-block:: csharp
 
@@ -75,7 +214,7 @@ perform the following operations:
    // Builds aggregation pipeline and specifies that the $vectorSearch stage
    // returns 10 results
    var pipeline = new EmptyPipelineDefinition<EmbeddedMovie>()
-      .VectorSearch(m => m.Embedding, vector, 10, options)
+      .VectorSearch(m => m.PlotEmbedding, vector, 10, options)
       .Project(Builders<EmbeddedMovie>.Projection
          .Include(m => m.Title)
          .Include(m => m.Plot)
@@ -96,5 +235,40 @@ The results of the preceding example contain the following documents:
    { "_id" : { "$oid" : "573a13b6f29313caabd477fa" }, "plot" : "With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.", "title" : "Love Story 2050", "score" : 0. 917755126953125 }
    { "_id" : { "$oid" : "573a13b3f29313caabd3ebd4" }, "plot" : "A romantic drama about a Chicago librarian with a gene that causes him to involuntarily time travel, and the complications it creates for his marriage.", "title" : "The Time Traveler's Wife", "score" : 0.9172210693359375 }
 
-To learn more about Atlas Vector Search, see :atlas:`Atlas Vector Search Overview </atlas-vector-search/vector-search-overview/>`
-in the Atlas manual.
+LINQ Example
+~~~~~~~~~~~~
+
+The following code sample performs the same vector search query as the preceding example, but uses
+the LINQ syntax instead of the aggregation pipeline syntax:
+
+.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchQueryExample.cs
+   :language: csharp
+   :start-after: start-linq-example
+   :end-before: end-linq-example
+   :dedent:
+   :emphasize-lines: 2
+
+Additional Information
+----------------------
+
+To learn more about {+avs+}, see the :atlas:`{+avs+}
+</atlas-vector-search/vector-search-overview/>` guide in the MongoDB Atlas
+documentation.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the functions or types discussed in this
+guide, see the following API Documentation:
+
+- `BinaryVectorFloat32 <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BinaryVectorFloat32.html>`__
+- `BinaryVectorInt8 <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BinaryVectorInt8.html>`__
+- `BinaryVectorPackedBit <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BinaryVectorPackedBit.html>`__
+- `QueryVector <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.QueryVector.html>`__
+- `ToQueryVector() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.BinaryVectorDriverExtensions.ToQueryVector.html>`__
+- `IAggregateFluentExtensions.VectorSearch() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IAggregateFluentExtensions.VectorSearch.html>`__
+- `Aggregate()
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Aggregate.html>`__
+- `MongoQueryable.VectorSearch() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.VectorSearch.html>`__
+- `PipelineStageDefinitionBuilder.VectorSearch()
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineStageDefinitionBuilder.VectorSearch.html>`__