DOCSP-45096: binaryvector type for avs

snooty.toml

@@ -12,6 +12,7 @@ toc_landing_pages = [
     "/fundamentals/builders",
     "/fundamentals/aggregation",
     "/usage-examples",
+    "/fundamentals/builders/aggregates",
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/fundamentals/builders.txt

@@ -4,8 +4,6 @@
 Builders
 ========
 
-.. default-domain:: mongodb
-
 .. toctree::
 
    Aggregation </fundamentals/builders/aggregates>

source/fundamentals/builders/aggregates.txt

@@ -15,6 +15,10 @@ Aggregates Builders
    :depth: 2
    :class: singlecol
 
+.. toctree::
+
+   Atlas Vector Search </fundamentals/builders/vector-search>
+
 .. _aggregates-builders:
 
 Overview
@@ -182,7 +186,6 @@ value of the ``title`` field:
    :language: java
    :dedent:
 
-
 Skip
 ----
 
@@ -980,49 +983,3 @@ aggregation stage:
 
 Learn more about this helper from the
 `searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__.
-
-.. _java-atlas-vector-search:
-
-Atlas Vector Search
--------------------
-
-.. important::
-
-   To learn what versions of MongoDB Atlas support this feature, see
-   :atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
-   in the MongoDB Atlas documentation.
-
-Use the ``vectorSearch()`` method to create a :atlas:`$vectorSearch
-</atlas-vector-search/vector-search-stage/>`
-pipeline stage that specifies a **semantic search**. A semantic search is
-a type of search which locates information that is similar in meaning.
-
-To use this feature, you must set up a vector search index and index your
-vector embeddings. To learn about how to programmatically create a
-vector search index, see the :ref:`java-search-indexes` section in the Indexes guide. To
-learn more about vector embeddings, see
-:atlas:`How to Index Vector Embeddings for Vector Search
-</atlas-search/field-types/knn-vector/>`.
-
-The following example shows how to build an aggregation pipeline that uses the
-``vectorSearch()`` and ``project()`` methods to compute a vector search score:
-
-.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java
-   :start-after: // begin vectorSearch
-   :end-before: // end vectorSearch
-   :language: java
-   :dedent:
-
-The following example shows how you can print the score from the result of the
-preceding aggregation pipeline:
-
-.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java
-   :start-after: // begin vectorSearch-output
-   :end-before: // end vectorSearch-output
-   :language: java
-   :dedent:
-
-Learn more about this helper in the
-`vectorSearch()
-<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#vectorSearch(com.mongodb.client.model.search.FieldSearchPath,java.lang.Iterable,java.lang.String,long,com.mongodb.client.model.search.VectorSearchOptions)>`__
-API documentation.

source/fundamentals/builders/vector-search.txt

@@ -0,0 +1,106 @@
+.. _java-atlas-vector-search:
+
+===================
+Atlas Vector Search
+===================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, semantic, nearest
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the :atlas:`Atlas Vector Search
+</atlas-vector-search/vector-search-overview/>` feature
+in the {+driver-short+}. The ``Aggregates``  builders class provides the
+the ``vectorSearch()`` helper method that you can use to
+create a :atlas:`$vectorSearch </atlas-vector-search/vector-search-stage/>`
+pipeline stage. This pipeline stage allows you to perform a **semantic
+search** on your documents. A semantic search is a type of search which
+locates information that is similar in meaning, but not necessarily
+identical, to your provided search term or phrase.
+
+.. important:: Feature Compatibility
+
+   To learn what versions of MongoDB Atlas support this feature, see
+   :atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
+   in the MongoDB Atlas documentation.
+
+Perform a Vector Search
+-----------------------
+
+To use this feature, you must create a vector search index and index your
+vector embeddings. To learn about how to programmatically create a
+vector search index, see the :ref:`java-search-indexes` section in the
+Indexes guide. To learn more about vector embeddings, see
+:atlas:`How to Index Vector Embeddings for Vector Search
+</atlas-search/field-types/knn-vector/>` in the Atlas documentation.
+
+After you create a vector search index on your vector embeddings, you
+can reference this index in your pipeline stage, as shown in the
+following section.
+
+Vector Search Example
+~~~~~~~~~~~~~~~~~~~~~
+
+The following example shows how to build an aggregation pipeline that uses the
+``vectorSearch()`` and ``project()`` methods to compute a vector search score:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java
+   :start-after: // begin vectorSearch
+   :end-before: // end vectorSearch
+   :language: java
+   :dedent:
+
+.. tip:: Query Vector Type
+
+   The preceding example creates an instance of ``BinaryVector`` to
+   serve as the query vector, but you can also create a ``List`` of
+   ``Double`` instances. However, we recommend that you use the
+   ``BinaryVector`` type to improve storage efficiency.
+
+The following example shows how you can run the aggregation and print
+the vector search meta-score from the result of the preceding
+aggregation pipeline:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java
+   :start-after: // begin vectorSearch-output
+   :end-before: // end vectorSearch-output
+   :language: java
+   :dedent:
+
+.. tip:: Java Driver Vector Search Examples
+
+   Visit the :atlas:`Atlas documentation </atlas-vector-search/tutorials/>`
+   to find more tutorials on using the {+driver-short+} to perform Atlas
+   Vector Searches.
+
+API Documentation
+-----------------
+
+To learn more about the methods and types mentioned in this
+guide, see the following API documentation:
+
+- `Aggregates.vectorSearch()
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#vectorSearch(com.mongodb.client.model.search.FieldSearchPath,java.lang.Iterable,java.lang.String,long,com.mongodb.client.model.search.VectorSearchOptions)>`__
+
+- `FieldSearchPath
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/FieldSearchPath.html>`__
+
+- `VectorSearchOptions
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/VectorSearchOptions.html>`__
+
+- `Projections.metaVectorSearchScore()
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html#metaVectorSearchScore(java.lang.String)>`__
+
+.. TODO add BinaryVector API link

source/fundamentals/indexes.txt

@@ -220,7 +220,7 @@ Search, see the :atlas:`Atlas Search Indexes
 
 Atlas Vector Search enables you to perform semantic searches on vector
 embeddings stored in MongoDB Atlas. To learn more about Atlas Vector Search, see the
-:ref:`java-atlas-vector-search` section in the Aggregates Builder guide.
+:ref:`java-atlas-vector-search` guide.
 
 You can call the following methods on a collection to manage your Atlas
 Search and Vector Search indexes:

source/includes/fundamentals/code-snippets/builders/AggBuilders.java

@@ -314,12 +314,24 @@ private void matchStage() {
     private void vectorSearchPipeline() {
 
         // begin vectorSearch
-        List<Double> queryVector = (asList(-0.0072121937, -0.030757688, -0.012945653));
+        // Create an instance of the BinaryVector class as the query vector
+        BinaryVector queryVector = BinaryVector.floatVector(
+            new float[]{0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f});
+
+        // Specify the index name for the vector embedding index
         String indexName = "mflix_movies_embedding_index";
+
+        // Specify the path of the field to search on
         FieldSearchPath fieldSearchPath = fieldPath("plot_embedding");
+
+        // Limit the number of matches to 1
         int limit = 1;
-        VectorSearchOptions options = exactVectorSearchOptions().filter(gte("year", 2016));
 
+        // Create a pre-filter to only search within a subset of documents
+        VectorSearchOptions options = exactVectorSearchOptions()
+            .filter(gte("year", 2016));
+
+        // Create the vectorSearch pipeline stage
         List<Bson> pipeline = asList(
                 vectorSearch(
                         fieldSearchPath,

source/whats-new.txt

@@ -43,7 +43,7 @@ and features:
    .. replacement:: vector-type-example-link
 
       To learn about how to use this type when using the Atlas
-      Vector Search feature, see the TODO add link :ref:`` guide.
+      Vector Search feature, see the :ref:`java-atlas-vector-search` guide.
 
 - Adds a client bulk write API that allows you to perform write operations on multiple
   databases and collections at once. To learn more about this feature, see the