Skip to content

Commit e77be7b

Browse files
lindseymoorelindseymoore
committed
DOCSP-47141 Atlas Vector Search and Binary Vector Support (mongodb#473)
* DOCSP-47141 Atlas Vector Search and Binary Vector Support * add better comments * move page location * api docs * edits * links and fix bson vector code ex * RR comments * edits * edit * numcandidates edit * RR edits * QH comments * remove TODO * missing score text * update whats new and indexes page (cherry picked from commit 0eca024)
1 parent 961a895 commit e77be7b

File tree

5 files changed

+359
-1
lines changed

5 files changed

+359
-1
lines changed

‎source/fundamentals.txt

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Fundamentals
1313
Enterprise Authentication </fundamentals/enterprise-auth>
1414
BSON </fundamentals/bson>
1515
CRUD Operations </fundamentals/crud>
16+
Atlas Vector Search </fundamentals/atlas-vector-search>
1617
Aggregation </fundamentals/aggregation>
1718
Indexes </fundamentals/indexes>
1819
Transactions </fundamentals/transactions>

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

+174
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
.. _golang-atlas-vector-search:
2+
3+
================================
4+
Run an Atlas Vector Search Query
5+
================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, semantic, nearest
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the :atlas:`Atlas Vector Search
24+
</atlas-vector-search/vector-search-overview/>` feature
25+
in the {+driver-short+} by using the :atlas:`$vectorSearch </atlas-vector-search/vector-search-stage/>`
26+
pipeline stage. This pipeline stage allows you to perform a **semantic
27+
search** on your documents. A semantic search is a type of search which
28+
locates information that is similar in meaning, but not necessarily
29+
identical, to your provided search term or phrase.
30+
31+
.. important:: Feature Compatibility
32+
33+
To learn what versions of MongoDB Atlas support this feature, see
34+
:atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
35+
in the MongoDB Atlas documentation.
36+
37+
Sample Data
38+
~~~~~~~~~~~
39+
40+
The example on this page queries the ``plot_embedding`` field from the
41+
``embedded_movies`` collection, found in the
42+
:atlas:`sample_mflix </sample-data/sample-mflix>` database of the Atlas sample
43+
datasets.
44+
45+
The ``plot_embedding`` field contains vector embeddings with 1536 dimensions,
46+
created using OpenAI's ``text-embedding-ada-002`` embedding model.
47+
48+
To learn how to create a free MongoDB Atlas cluster and
49+
load the sample datasets, see the :atlas:`Get Started with Atlas
50+
</getting-started>` guide.
51+
52+
Perform a Vector Search
53+
-----------------------
54+
55+
To use this feature, you must create a vector search index and index your
56+
vector embeddings. To learn about how to programmatically create a
57+
vector search index, see the :ref:`golang-atlas-search-indexes` section in the
58+
Indexes guide. To learn more about vector embeddings, see
59+
:atlas:`How to Index Vector Embeddings for Vector Search
60+
</atlas-search/field-types/knn-vector/>` in the Atlas documentation.
61+
62+
After you create a vector search index on your vector embeddings, you
63+
can reference this index in your aggregation pipeline to run your vector
64+
search query.
65+
66+
The following sections demonstrate how to create a BSON binary vector
67+
for your query vector and how to use your vector search index to run a
68+
vector search query by using the ``plot_embedding`` field.
69+
70+
Create a BSON Binary Vector
71+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
72+
73+
In this example, you can create a 1536 dimensional vector to use as the query
74+
vector for your vector search query on the ``plot_embedding`` field.
75+
The query searches the ``plot_embedding`` field by using a vector
76+
embedding for the string "time travel".
77+
78+
The following example shows how to translate this vector embedding to a BSON
79+
binary vector that you can use as the query vector:
80+
81+
.. literalinclude:: /includes/fundamentals/code-snippets/vectorSearchQuery.go
82+
:language: go
83+
:start-after: start-binary-vector
84+
:end-before: end-binary-vector
85+
:dedent:
86+
87+
If you need to access a slice of the original vector, you can also deserialize
88+
your query vector back to a BSON vector.
89+
90+
The following example shows how to convert the query vector from a BSON binary
91+
vector to a BSON vector by using the ``NewVectorFromBinary()`` method:
92+
93+
.. literalinclude:: /includes/fundamentals/code-snippets/vectorSearchQuery.go
94+
:language: go
95+
:start-after: start-convert-back-vector
96+
:end-before: end-convert-back-vector
97+
:dedent:
98+
99+
.. tip:: Query Vector Type
100+
101+
The preceding example creates an instance of a BSON binary vector to
102+
serve as the query vector, but you can also use an array of BSON ``double``
103+
values. However, we recommend that you use a BSON binary vector to improve
104+
storage efficiency.
105+
106+
Run the Vector Search Query
107+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
108+
109+
The following example shows how to build an aggregation pipeline that uses the
110+
``$vectorSearch`` and ``$project`` methods to perform an Approximate Nearest
111+
Neighbor (ANN) vector search with the following specifications:
112+
113+
- Queries the ``plot_embedding`` field with the BSON binary ``queryVector``
114+
- Sets the number of nearest neighbors used in the search to 150 by using the
115+
``numCandidates`` option
116+
- Uses the ``vector_search`` index created on the ``plot_embedding`` field
117+
- Returns 5 documents with the specified ``plot``, ``title``, and ``score`` fields
118+
119+
.. io-code-block::
120+
:copyable: true
121+
122+
.. input:: /includes/fundamentals/code-snippets/vectorSearchQuery.go
123+
:language: go
124+
:start-after: start-aggregation
125+
:end-before: end-aggregation
126+
:dedent:
127+
128+
.. output::
129+
:language: none
130+
:visible: false
131+
132+
Title: Thrill Seekers
133+
Plot: A reporter, learning of time travelers visiting 20th century disasters, tries to change the history they know by averting upcoming disasters.
134+
Score: 0.92730712890625
135+
136+
Title: About Time
137+
Plot: At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.
138+
Score: 0.926605224609375
139+
140+
Title: The Time Machine
141+
Plot: Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.
142+
Score: 0.9239959716796875
143+
144+
Title: Timecop
145+
Plot: An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.
146+
Score: 0.923583984375
147+
148+
Title: Crusade in Jeans
149+
Plot: After using his mother's newly built time machine, Dolf gets stuck involuntary in the year 1212. He ends up in a children's crusade where he confronts his new friends with modern techniques...
150+
Score: 0.9222412109375
151+
152+
Additional Information
153+
----------------------
154+
155+
To learn more about Atlas Vector Search, see the :atlas:`Atlas Vector Search
156+
</atlas-vector-search/vector-search-overview/>` guides in
157+
the MongoDB Atlas documentation.
158+
159+
To learn more about the syntax of the ``$vectorSearch`` pipeline stage,
160+
see the Syntax and Fields sections of the
161+
:atlas:`Create and Run Queries </atlas-vector-search/vector-search-stage/#syntax>`
162+
guide in the Atlas Vector Search section of the MongoDB Atlas documentation.
163+
164+
API Documentation
165+
~~~~~~~~~~~~~~~~~
166+
167+
To learn more about any of the methods or types discussed in this
168+
guide, see the following API Documentation:
169+
170+
- `NewVector() <{+api+}/bson#NewVector>`__
171+
- `NewVectorfromBinary() <{+api+}/bson#NewVectorFromBinary>`__
172+
- `Vector <{+api+}/bson#Vector>`__
173+
- `Aggregate() <{+api+}/mongo#Collection.Aggregate>`__
174+
- `Pipeline <{+api+}/mongo#Pipeline>`__

‎source/fundamentals/indexes.txt

+94
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,100 @@ field in the ``sample_mflix.movies`` collection:
243243

244244
Name of Index Created: cast_-1
245245

246+
.. _golang-atlas-search-indexes:
247+
248+
Atlas Search and Atlas Vector Search Indexes
249+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
250+
251+
You can programmatically manage your Atlas Search and Atlas Vector
252+
Search indexes by using the {+driver-short+}.
253+
254+
The Atlas Search feature enables you to perform full-text searches on
255+
collections hosted on MongoDB Atlas. To learn more about Atlas
256+
Search, see the :atlas:`Atlas Search
257+
</atlas-search/atlas-search-overview/>` documentation.
258+
259+
Atlas Vector Search enables you to perform semantic searches on vector
260+
embeddings stored in Atlas. To learn more about Atlas
261+
Vector Search, see the :atlas:`Atlas Vector Search
262+
</atlas-vector-search/vector-search-overview/>` documentation.
263+
264+
To learn more about how to run Atlas Vector Search queries, see the
265+
:ref:`golang-atlas-vector-search` guide.
266+
267+
The following sections contain code examples that demonstrate how to manage Atlas
268+
Search and Atlas Vector Search indexes.
269+
270+
Create a Search Index
271+
`````````````````````
272+
273+
You can create an Atlas Search or an Atlas Vector Search index by providing
274+
an index definition to the ``SearchIndexView.CreateOne()`` method.
275+
276+
The following example creates an Atlas Search index on the ``plot`` field of the
277+
``sample_mflix.movies`` collection:
278+
279+
.. literalinclude:: /includes/fundamentals/code-snippets/indexes/atlasVectorSearch.go
280+
:language: go
281+
:start-after: start-create-atlas-search
282+
:end-before: end-create-atlas-search
283+
:dedent:
284+
285+
The following example creates an Atlas Vector Search index on the ``plot_embedding``
286+
field in the ``sample_mflix.embedded_movies`` collection:
287+
288+
.. literalinclude:: /includes/fundamentals/code-snippets/indexes/atlasVectorSearch.go
289+
:language: go
290+
:start-after: start-create-vector-search
291+
:end-before: end-create-vector-search
292+
:dedent:
293+
294+
List a Search Index
295+
```````````````````
296+
297+
You can use the ``SearchIndexView.List()`` method to list an Atlas Search or Atlas
298+
Vector Search index by specifying the name of the index.
299+
300+
The following example lists the details of the specified Atlas Search or Atlas
301+
Vector Search index:
302+
303+
.. literalinclude:: /includes/fundamentals/code-snippets/indexes/atlasVectorSearch.go
304+
:language: go
305+
:start-after: start-list-index
306+
:end-before: end-list-index
307+
:dedent:
308+
309+
Update a Search Index
310+
`````````````````````
311+
312+
You can use the ``SearchIndexView.UpdateOne()`` method to update an Atlas Search
313+
or Atlas Vector Search index by specifying the name of the index and the new
314+
index definition.
315+
316+
The following example updates an Atlas Vector Search index by providing the name
317+
of the index and a new index definition:
318+
319+
.. literalinclude:: /includes/fundamentals/code-snippets/indexes/atlasVectorSearch.go
320+
:language: go
321+
:start-after: start-update-index
322+
:end-before: end-update-index
323+
:dedent:
324+
325+
Delete a Search Index
326+
`````````````````````
327+
328+
You can use the ``SearchIndexView.DropOne()`` method to delete an Atlas Search or
329+
Atlas Vector Search index by specifying the name of the index.
330+
331+
The following example deletes an Atlas Search or Atlas Vector Search
332+
index with the specified name:
333+
334+
.. literalinclude:: /includes/fundamentals/code-snippets/indexes/atlasVectorSearch.go
335+
:language: go
336+
:start-after: start-delete-index
337+
:end-before: end-delete-index
338+
:dedent:
339+
246340
.. _golang-clustered-indexes:
247341

248342
Clustered Indexes

0 commit comments

Comments
 (0)