Skip to content

Commit 0eca024

Browse files
lindseymoorelindseymoore
authored
DOCSP-47141 Atlas Vector Search and Binary Vector Support (#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
1 parent 0b2a4ba commit 0eca024

File tree

5 files changed

+267
-3
lines changed

5 files changed

+267
-3
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

+2-2
Original file line numberDiff line numberDiff line change
@@ -261,8 +261,8 @@ embeddings stored in Atlas. To learn more about Atlas
261261
Vector Search, see the :atlas:`Atlas Vector Search
262262
</atlas-vector-search/vector-search-overview/>` documentation.
263263

264-
.. Add when Go AVS guide is ready:
265-
.. To learn more about Atlas Vector Search, see the :ref:`golang-atlas-vector-search` guide.
264+
To learn more about how to run Atlas Vector Search queries, see the
265+
:ref:`golang-atlas-vector-search` guide.
266266

267267
The following sections contain code examples that demonstrate how to manage Atlas
268268
Search and Atlas Vector Search indexes.

0 commit comments

Comments
 (0)