Skip to content

Commit 057727c

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-46179 Vector Search (#498)
1 parent 78c9a0d commit 057727c

File tree

6 files changed

+321
-0
lines changed

6 files changed

+321
-0
lines changed

‎snooty.toml

+1
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,4 @@ not-available = "N/A"
4848
analyzer = "MongoDB C# Analyzer"
4949
analyzer-short = "C# Analzyer"
5050
query-api = "MongoDB Query API"
51+
vector-search = "Atlas Vector Search"

‎source/fundamentals.txt

+2
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Fundamentals
1616
CRUD Operations </fundamentals/crud>
1717
Operations with Builders </fundamentals/builders>
1818
Atlas Search </fundamentals/atlas-search>
19+
Atlas Vector Search </fundamentals/atlas-vector-search>
1920
Stable API </fundamentals/stable-api>
2021
Authentication </fundamentals/authentication>
2122
Aggregation </fundamentals/aggregation>
@@ -39,6 +40,7 @@ Fundamentals
3940
- :ref:`csharp-crud`
4041
- :ref:`csharp-builders`
4142
- :ref:`csharp-atlas-search`
43+
- :ref:`csharp-atlas-vector-search`
4244
- :ref:`csharp-stable-api`
4345
- :ref:`csharp-authentication-mechanisms`
4446
- :ref:`csharp-aggregation`

‎source/fundamentals/atlas-vector-search.txt

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
.. _csharp-atlas-vector-search:
2+
3+
===================
4+
{+vector-search+}
5+
===================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: .NET, search, semantic, AI, RAG
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
You can use {+vector-search+} to perform vector search on your data stored in
24+
Atlas. Vector search allows you to query your data based on semantic meaning
25+
rather than just keyword matches, which helps you retrieve more relevant search
26+
results. It enables your AI-powered applications to support use cases such as
27+
semantic search, hybrid search, and generative search, including
28+
Retrieval-Augmented Generation (RAG).
29+
30+
By using Atlas as a vector database, you can seamlessly index vector data along
31+
with your other data in Atlas. This allows you to filter on fields in your
32+
collection and perform vector search queries against vector data. You can also
33+
combine vector search with full-text search queries to return the most relevant
34+
results for your use case. You can integrate {+vector-search+} with popular AI
35+
frameworks and services to easily implement vector search in your applications.
36+
37+
To learn more about {+vector-search+}, see the :atlas:`{+vector-search+}
38+
</atlas-vector-search/vector-search-overview/>` guide in the MongoDB Atlas
39+
documentation.
40+
41+
Supported Vector Embedding Types
42+
--------------------------------
43+
44+
:atlas:`Vector embeddings
45+
</atlas-vector-search/vector-search-overview/#std-term-vector-embeddings>`
46+
are vectors you use to represent your data. These embeddings
47+
capture meaningful relationships in your data and enable tasks like semantic
48+
search and retrieval.
49+
50+
The {+driver-short+} supports vector embeddings of several types. The following
51+
sections describe the supported vector embedding types.
52+
53+
54+
.. _csharp-vector-array-representation:
55+
56+
Array Representations
57+
~~~~~~~~~~~~~~~~~~~~~
58+
59+
The {+driver-short+} supports the following representations of the array
60+
type in vector embeddings:
61+
62+
- ``BsonArray``
63+
- ``Memory``
64+
- ``ReadOnlyMemory``
65+
- ``float[]`` and ``double[]``
66+
67+
The following example shows a class with properties of the preceding types:
68+
69+
.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
70+
:language: csharp
71+
:start-after: start-bson-arrays
72+
:end-before: end-bson-arrays
73+
74+
.. _csharp-binary-vector-representation:
75+
76+
Binary Vector Representations
77+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78+
79+
The {+driver-short+} supports the following binary vector representations in
80+
vector embeddings:
81+
82+
- ``BinaryVectorFloat32`` (not supported on big-endian architectures)
83+
- ``BinaryVectorInt8``
84+
- ``BinaryVectorPackedBit``
85+
- ``Memory<float>``, ``Memory<byte>``, ``Memory<sbyte>``
86+
- ``ReadOnlyMemory<float>``, ``ReadOnlyMemory<byte>``, ``ReadOnlyMemory<sbyte>``
87+
- ``float[]``, ``byte[]``, ``sbyte[]``
88+
89+
.. note::
90+
91+
You must use the ``BinaryVector`` attribute when specifying binary vector
92+
representations of the ``Memory<T>``, ``ReadOnlyMemory<T>``, or array
93+
types.
94+
95+
The following example shows a class with properties of the preceding types:
96+
97+
.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
98+
:language: csharp
99+
:start-after: start-binary-vectors
100+
:end-before: end-binary-vectors
101+
102+
Binary Vector Data Serialization
103+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104+
105+
You can serialize ``Int8`` binary vector typed data as ``byte`` or ``sbyte``.
106+
You can also serialize ``Float32`` binary vector typed data as ``float``. The
107+
following example serializes ``Int8`` and ``Float32`` binary vector data:
108+
109+
.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
110+
:language: csharp
111+
:start-after: start-binary-int-float-serialize
112+
:end-before: end-binary-int-float-serialize
113+
114+
You can deserialize ``PackedBit`` vector data to a :ref:`binary vector
115+
represented <csharp-binary-vector-representation>` ``byte`` data type only if the
116+
vector data has a padding value of ``0``. If the vector data has a padding value not
117+
equal to ``0``, you can deserialize it only to a ``BsonVectorPackedBit``.
118+
119+
Vector Search Query Example
120+
---------------------------
121+
122+
You can perform a vector search query by calling the ``VectorSearch()`` method
123+
in an :ref:`aggregation pipeline <csharp-aggregation>`. To perform a vector
124+
search on a collection, you must first have a collection with a field that contains
125+
vector data and a vector search index that covers that field.
126+
127+
.. tip::
128+
129+
To learn more about configuring a collection for vector search, see the :atlas:`{+vector-search+}
130+
</atlas-vector-search/vector-search-overview/>` guide in the MongoDB Atlas
131+
documentation.
132+
133+
You can convert ``BinaryVectorFloat32``, ``BinaryVectorInt8``, and
134+
``BinaryVectorPackedBit`` data to the ``BsonBinaryData`` type to use in a vector
135+
search query by using the ``ToQueryVector()`` method. The following example
136+
converts ``BinaryVectorInt8`` into a ``BsonBinaryData`` object:
137+
138+
.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
139+
:language: csharp
140+
:start-after: start-to-query-vector
141+
:end-before: end-to-query-vector
142+
143+
You can specify your :ref:`array-represented
144+
<csharp-vector-array-representation>` vector data as an instance of the
145+
``QueryVector`` class to use in a vector search query. The following example
146+
creates an array of ``ReadOnlyMemory<float>`` values as a ``QueryVector`` object
147+
to use in a vector search query:
148+
149+
.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs
150+
:language: csharp
151+
:start-after: start-array-query-vector
152+
:end-before: end-array-query-vector
153+
154+
Example
155+
~~~~~~~
156+
157+
This example performs the following steps to run an {+vector-search+} query on a collection that
158+
contains vector data and a vector search index on the ``PlotEmbedding`` field:
159+
160+
1. Creates an array that contains the :ref:`array-represented
161+
<csharp-vector-array-representation>` vector data to search for
162+
#. Specifies a ``VectorSearchOptions`` object that contains the name of the index
163+
and the number of nearest neighbors to use during the search
164+
#. Creates an aggregation pipeline that uses the ``VectorSearch()`` stage to
165+
perform the vector search query and a ``Project()`` stage to filter the
166+
results
167+
#. Prints the results of the query
168+
169+
.. literalinclude:: /includes/fundamentals/code-examples/atlas-vector-search/VectorSearchQueryExample.cs
170+
:language: csharp
171+
:start-after: start-search-example
172+
:end-before: end-search-example
173+
:emphasize-lines: 11
174+
175+
Additional Information
176+
----------------------
177+
178+
To learn more about {+vector-search+}, see the :atlas:`{+vector-search+}
179+
</atlas-vector-search/vector-search-overview/>` guide in the MongoDB Atlas
180+
documentation.
181+
182+
API Documentation
183+
~~~~~~~~~~~~~~~~~
184+
185+
To learn more about any of the functions or types discussed in this
186+
guide, see the following API Documentation:
187+
188+
- `BinaryVectorFloat32 <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BinaryVectorFloat32.html>`__
189+
- `BinaryVectorInt8 <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BinaryVectorInt8.html>`__
190+
- `BinaryVectorFloat32 <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BinaryVectorPackedBit.html>`__
191+
- `ToQueryVector() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.BinaryVectorDriverExtensions.ToQueryVector.html>`__
192+
- `VectorSearch() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateFluentBase-1.VectorSearch.html>`__
193+
- `Aggregate() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Aggregate.html>`__

‎source/includes/fundamentals/code-examples/atlas-vector-search/VectorSearchExamples.cs

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// start-bson-arrays
2+
public class BsonArrayVectors
3+
{
4+
public BsonArray BsonArrayVector { get; set; }
5+
6+
public Memory<float> MemoryVector { get; set; }
7+
8+
public ReadOnlyMemory<float> ReadOnlyMemoryVector { get; set; }
9+
10+
public float[] FloatArrayVector { get; set; }
11+
}
12+
// end-bson-arrays
13+
14+
// start-binary-vectors
15+
public class BinaryVectors
16+
{
17+
public BinaryVectorInt8 ValuesInt8 { get; set; }
18+
19+
public BinaryVectorPackedBit ValuesPackedBit { get; set; }
20+
21+
public BinaryVectorFloat32 ValuesFloat { get; set; }
22+
23+
[BinaryVector(BinaryVectorDataType.Int8)]
24+
public Memory<byte> ValuesByte { get; set; }
25+
26+
[BinaryVector(BinaryVectorDataType.Float32)]
27+
public float[] ValuesFloat { get; set; }
28+
29+
}
30+
// end-binary-vectors
31+
32+
// start-binary-int-float-serialize
33+
[BinaryVector(BinaryVectorDataType.Int8)]
34+
public Memory<byte> ValuesByte { get; set; }
35+
36+
[BinaryVector(BinaryVectorDataType.Int8)]
37+
public Memory<sbyte> ValuesSByte { get; set; }
38+
39+
[BinaryVector(BinaryVectorDataType.Float32)]
40+
public float[] ValuesFloat { get; set; }
41+
// end-binary-int-float-serialize
42+
43+
// start-to-query-vector
44+
var binaryVector = new BinaryVectorInt8(new sbyte[] { 0, 1, 2, 3, 4 });
45+
46+
var queryVector = binaryVector.ToQueryVector();
47+
// end-to-query-vector
48+
49+
// start-array-query-vector
50+
QueryVector v = new QueryVector(new ReadOnlyMemory<float>([1.2f, 2.3f]));
51+
// end-array-query-vector

‎source/includes/fundamentals/code-examples/atlas-vector-search/VectorSearchQueryExample.cs

+64
Large diffs are not rendered by default.

‎source/whats-new.txt

+10
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,16 @@ The 3.2 driver release includes the following new features:
6161
- Optimizes client-side projections to retrieve only the required fields from
6262
the server, rather than retrieving all fields and then filtering them.
6363

64+
- Adds the following classes to support binary vector representations in Atlas
65+
Vector Search:
66+
67+
- ``BinaryVectorFloat32``
68+
- ``BinaryVectorInt8``
69+
- ``BinaryVectorPackedBit``
70+
71+
To learn more about Atlas Vector Search with the {+driver-short+}, see the
72+
:ref:`csharp-atlas-vector-search` guide.
73+
6474
.. _csharp-version-3.1:
6575

6676
What's New in 3.1

0 commit comments

Comments
 (0)