From d06ddf94f3db4070bb09672f5f632f78da787b7d Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 10:07:11 -0500 Subject: [PATCH 1/7] add vector search params --- source/fundamentals/builders.txt | 8 ++- source/fundamentals/linq.txt | 2 + source/includes/vector-search-parameters.rst | 68 ++++++++++++++++++++ 3 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 source/includes/vector-search-parameters.rst diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 0f2cdcc5..9dfd458a 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -439,6 +439,8 @@ have a defined Atlas Vector Search index before you can perform a vector search :atlas:`Create an Atlas Vector Search Index ` in the Atlas manual. +.. include:: /includes/vector-search-parameters.rst + 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. @@ -446,7 +448,8 @@ field of the documents in the collection. The following example shows how to use builders to generate an aggregation pipeline to perform the following operations: -- Performs a vector search on the Atlas Vector Search index of the ``plot_embedding`` field using vector embeddings for the string ``"time travel"`` +- 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 .. code-block:: csharp @@ -485,7 +488,8 @@ The results of the preceding example contain the following documents: { "_id" : ObjectId("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" } { "_id" : ObjectId("573a13e5f29313caabdc40c9"), "plot" : "A dimension-traveling wizard gets stuck in the 21st century because cell-phone radiation interferes with his magic. With his home world on the brink of war, he seeks help from a jaded ...", "title" : "The Portal" } -To learn more about Atlas Vector Search, see :atlas:`Atlas Vector Search Overview ` +To learn more about Atlas Vector Search, see +:atlas:`Atlas Vector Search Overview ` in the Atlas manual. Additional Information diff --git a/source/fundamentals/linq.txt b/source/fundamentals/linq.txt index 85db94ab..846169a5 100644 --- a/source/fundamentals/linq.txt +++ b/source/fundamentals/linq.txt @@ -640,6 +640,8 @@ defined Atlas Vector Search index before you can perform a vector search on your :atlas:`Create an Atlas Vector Search Index ` in the Atlas manual. +.. include:: /includes/vector-search-parameters.rst + 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. diff --git a/source/includes/vector-search-parameters.rst b/source/includes/vector-search-parameters.rst new file mode 100644 index 00000000..de953bcd --- /dev/null +++ b/source/includes/vector-search-parameters.rst @@ -0,0 +1,68 @@ +To create a ``$vectorSearch`` pipeline stage, call the ``VectorSearch()`` method on a +``PipelineStageDefinitionBuilder`` object. The ``VectorSearch()`` method accepts the +following parameters: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Parameter + - Description + + * - ``field`` + - The field to perform the vector search on. + + **Data type**: ``Expression>`` + + * - ``queryVector`` + - The encoded vector that will be matched with values from the database. + Although the data type of this parameter is ``QueryVector``, you can also pass an + array of floating-point numbers. + + **Data type**: `QueryVector <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.QueryVector.html>`__ + + * - ``limit`` + - The maximum number of documents to return. + + **Data type**: {+int-data-type+} + + * - ``options`` + - Configuration options for the vector search operation. + + **Data type**: `VectorSearchOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.VectorSearchOptions-1.html>`__ + +You can use the ``options`` parameter to configure your vector search operation. The +``VectorSearchOptions`` class contains the following properties: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Property + - Description + + * - ``Exact`` + - Whether the vector search uses the exact nearest neighbor (ENN) algorithm. + If this property is set to ``false``, the vector search uses the approximate nearest + neighbor (ANN) algorithm. + + **Data type**: {+bool-data-type+} + **Default**: ``false`` + + * - ``Filter`` + - Additional search criteria that the found documents must match. + + **Data Type:** `FilterDefinition <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__ + **Default**: ``null`` + + * - ``IndexName`` + - The index to perform the vector search on. + + **Data type**: {+string-data-type+} + **Default**: ``null`` + + * - ``NumberOfCandidates`` + - The number of neighbors to search in the index. + + **Data type**: ``int?`` + **Default**: ``null`` \ No newline at end of file From e615796ed26b71656458ecd0407a5f78808c7e29 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 10:13:28 -0500 Subject: [PATCH 2/7] adjust col width --- source/includes/vector-search-parameters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/vector-search-parameters.rst b/source/includes/vector-search-parameters.rst index de953bcd..71224444 100644 --- a/source/includes/vector-search-parameters.rst +++ b/source/includes/vector-search-parameters.rst @@ -36,7 +36,7 @@ You can use the ``options`` parameter to configure your vector search operation. .. list-table:: :header-rows: 1 - :widths: 20 80 + :widths: 30 70 * - Property - Description From c4fec6a0d6538ea4165601237bbe69a731c863ed Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 10:23:08 -0500 Subject: [PATCH 3/7] fixes --- source/includes/vector-search-parameters.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/includes/vector-search-parameters.rst b/source/includes/vector-search-parameters.rst index 71224444..2c4f3755 100644 --- a/source/includes/vector-search-parameters.rst +++ b/source/includes/vector-search-parameters.rst @@ -44,25 +44,26 @@ You can use the ``options`` parameter to configure your vector search operation. * - ``Exact`` - Whether the vector search uses the exact nearest neighbor (ENN) algorithm. If this property is set to ``false``, the vector search uses the approximate nearest - neighbor (ANN) algorithm. + neighbor (ANN) algorithm. If this property is set to ``true``, the + ``NumberOfCandidates`` property must be ``null``. **Data type**: {+bool-data-type+} - **Default**: ``false`` + | **Default**: ``false`` * - ``Filter`` - Additional search criteria that the found documents must match. **Data Type:** `FilterDefinition <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__ - **Default**: ``null`` + | **Default**: ``null`` * - ``IndexName`` - The index to perform the vector search on. **Data type**: {+string-data-type+} - **Default**: ``null`` + | **Default**: ``null`` * - ``NumberOfCandidates`` - The number of neighbors to search in the index. **Data type**: ``int?`` - **Default**: ``null`` \ No newline at end of file + | **Default**: ``null`` \ No newline at end of file From 162171b8c19ed1ecca92c5d7d35058b094e7d107 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 10:46:51 -0500 Subject: [PATCH 4/7] fix --- source/includes/vector-search-parameters.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/includes/vector-search-parameters.rst b/source/includes/vector-search-parameters.rst index 2c4f3755..26b763a0 100644 --- a/source/includes/vector-search-parameters.rst +++ b/source/includes/vector-search-parameters.rst @@ -47,23 +47,23 @@ You can use the ``options`` parameter to configure your vector search operation. neighbor (ANN) algorithm. If this property is set to ``true``, the ``NumberOfCandidates`` property must be ``null``. - **Data type**: {+bool-data-type+} + | **Data type**: {+bool-data-type+} | **Default**: ``false`` * - ``Filter`` - Additional search criteria that the found documents must match. - **Data Type:** `FilterDefinition <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__ + | **Data Type:** `FilterDefinition <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__ | **Default**: ``null`` * - ``IndexName`` - The index to perform the vector search on. - **Data type**: {+string-data-type+} + | **Data type**: {+string-data-type+} | **Default**: ``null`` * - ``NumberOfCandidates`` - The number of neighbors to search in the index. - **Data type**: ``int?`` + | **Data type**: ``int?`` | **Default**: ``null`` \ No newline at end of file From 206f9fd885b22a31e0710136ed3dfc8dae89d157 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 11:24:00 -0500 Subject: [PATCH 5/7] lm feedback --- source/includes/vector-search-parameters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/vector-search-parameters.rst b/source/includes/vector-search-parameters.rst index 26b763a0..1f9533e9 100644 --- a/source/includes/vector-search-parameters.rst +++ b/source/includes/vector-search-parameters.rst @@ -17,7 +17,7 @@ following parameters: * - ``queryVector`` - The encoded vector that will be matched with values from the database. Although the data type of this parameter is ``QueryVector``, you can also pass an - array of floating-point numbers. + array of ``float`` values. **Data type**: `QueryVector <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.QueryVector.html>`__ From d8366fdc828b83cc0b429382e030a2f731b72632 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 14:11:00 -0500 Subject: [PATCH 6/7] bd feedback --- source/fundamentals/builders.txt | 21 +++-------- source/fundamentals/linq.txt | 36 ++----------------- ...parameters.rst => vector-search-intro.rst} | 32 +++++++++++++++-- 3 files changed, 36 insertions(+), 53 deletions(-) rename source/includes/{vector-search-parameters.rst => vector-search-intro.rst} (68%) diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 9dfd458a..38d79b56 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -428,29 +428,16 @@ To learn how to construct search queries with the ``Search`` class, see Perform an Atlas Vector Search ------------------------------ -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. +.. include:: /includes/vector-search-intro.rst -.. tip:: - - To obtain the sample dataset used in the following example, see :ref:`csharp-quickstart`. - To create the sample Atlas Vector Search index used in the following example, see - :atlas:`Create an Atlas Vector Search Index ` in the - Atlas manual. - -.. include:: /includes/vector-search-parameters.rst - -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`` +You can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding`` field of the documents in the collection. - The following example shows how to use builders to generate an aggregation pipeline to perform the following operations: -- Performs a vector search on the Atlas Vector Search index of the ``plot_embedding`` +- Perform 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 +- Fetch the ``Title`` and ``Plot`` fields from documents found in the vector search .. code-block:: csharp diff --git a/source/fundamentals/linq.txt b/source/fundamentals/linq.txt index 846169a5..94e679ec 100644 --- a/source/fundamentals/linq.txt +++ b/source/fundamentals/linq.txt @@ -629,42 +629,10 @@ The following shows a subset of the returned results: $vectorSearch ~~~~~~~~~~~~~ -The ``$vectorSearch`` aggregation stage performs 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. - -.. tip:: - - To obtain the sample dataset used in the following example, see :ref:`csharp-quickstart`. - To create the sample Atlas Vector Search index used in the following example, see - :atlas:`Create an Atlas Vector Search Index ` in the - Atlas manual. - -.. include:: /includes/vector-search-parameters.rst - -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 ``EmbeddedMovie`` class models the documents in the ``embedded_movies`` -collection: - -.. code-block:: csharp - - [BsonIgnoreExtraElements] - public class EmbeddedMovie - { - [BsonIgnoreIfDefault] - public string Title { get; set; } - - public string Plot { get; set; } - - [BsonElement("plot_embedding")] - public double[] Embedding { get; set; } - } +.. include:: /includes/vector-search-intro.rst The following example shows how to generate a ``$vectorSearch`` stage to search -the ``plot_embedding`` field using vector embeddings for the string ``"time travel"``: +the ``plot_embedding`` field by using vector embeddings for the string ``"time travel"``: .. code-block:: csharp diff --git a/source/includes/vector-search-parameters.rst b/source/includes/vector-search-intro.rst similarity index 68% rename from source/includes/vector-search-parameters.rst rename to source/includes/vector-search-intro.rst index 1f9533e9..b247d35d 100644 --- a/source/includes/vector-search-parameters.rst +++ b/source/includes/vector-search-intro.rst @@ -1,3 +1,14 @@ +The ``$vectorSearch`` aggregation stage performs 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. + +.. tip:: + + To obtain the sample dataset used in the following example, see :ref:`csharp-quickstart`. + To create the sample Atlas Vector Search index used in the following example, see + :atlas:`Create an Atlas Vector Search Index ` in the + Atlas manual. + To create a ``$vectorSearch`` pipeline stage, call the ``VectorSearch()`` method on a ``PipelineStageDefinitionBuilder`` object. The ``VectorSearch()`` method accepts the following parameters: @@ -60,10 +71,27 @@ You can use the ``options`` parameter to configure your vector search operation. - The index to perform the vector search on. | **Data type**: {+string-data-type+} - | **Default**: ``null`` + | **Default**: ``"default"`` * - ``NumberOfCandidates`` - The number of neighbors to search in the index. | **Data type**: ``int?`` - | **Default**: ``null`` \ No newline at end of file + | **Default**: ``null`` + +Consider the ``embedded_movies`` collection in the ``sample_mflix`` database. +The following ``EmbeddedMovie`` class represents a document in this database: + +.. code-block:: csharp + + public class EmbeddedMovie + { + [BsonElement("title")] + public string Title { get; set; } + + [BsonElement("plot_embedding")] + public double[] Embedding { get; set; } + + [BsonElement("score")] + public double Score { get; set; } + } \ No newline at end of file From a244df4f8e2756de93369ec06821fc4cc5941884 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 12 Mar 2025 15:32:46 -0500 Subject: [PATCH 7/7] bd feedback --- source/fundamentals/builders.txt | 11 +++-------- source/fundamentals/linq.txt | 5 +++-- source/includes/vector-search-intro.rst | 13 +++++++++++-- 3 files changed, 17 insertions(+), 12 deletions(-) diff --git a/source/fundamentals/builders.txt b/source/fundamentals/builders.txt index 38d79b56..e66e8372 100644 --- a/source/fundamentals/builders.txt +++ b/source/fundamentals/builders.txt @@ -430,14 +430,9 @@ Perform an Atlas Vector Search .. include:: /includes/vector-search-intro.rst -You can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding`` -field of the documents in the collection. -The following example shows how to use builders to generate an aggregation pipeline to -perform the following operations: - -- Perform a vector search on the Atlas Vector Search index of the ``plot_embedding`` - field using vector embeddings for the string ``"time travel"`` -- Fetch the ``Title`` and ``Plot`` fields from documents found in the vector search + .. replacement:: mechanism + + builders .. code-block:: csharp diff --git a/source/fundamentals/linq.txt b/source/fundamentals/linq.txt index 94e679ec..40feb0bc 100644 --- a/source/fundamentals/linq.txt +++ b/source/fundamentals/linq.txt @@ -631,8 +631,9 @@ $vectorSearch .. include:: /includes/vector-search-intro.rst -The following example shows how to generate a ``$vectorSearch`` stage to search -the ``plot_embedding`` field by using vector embeddings for the string ``"time travel"``: + .. replacement:: mechanism + + LINQ .. code-block:: csharp diff --git a/source/includes/vector-search-intro.rst b/source/includes/vector-search-intro.rst index b247d35d..c930af0b 100644 --- a/source/includes/vector-search-intro.rst +++ b/source/includes/vector-search-intro.rst @@ -71,7 +71,7 @@ You can use the ``options`` parameter to configure your vector search operation. - The index to perform the vector search on. | **Data type**: {+string-data-type+} - | **Default**: ``"default"`` + | **Default**: ``null`` * - ``NumberOfCandidates`` - The number of neighbors to search in the index. @@ -94,4 +94,13 @@ The following ``EmbeddedMovie`` class represents a document in this database: [BsonElement("score")] public double Score { get; set; } - } \ No newline at end of file + } + +You can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding`` +field of the documents in the collection. +The following example shows how to use |mechanism| to generate an aggregation pipeline to +perform the following operations: + +- Perform a vector search on the Atlas Vector Search index of the ``plot_embedding`` + field by using vector embeddings for the string ``"time travel"`` +- Fetch the ``Title`` and ``Plot`` fields from documents found in the vector search \ No newline at end of file