DOCSP-33234: add vectorSearch builder (#459)

* DOCSP-33234: add vectorSearch builder

Author: Chris Cho

source/fundamentals/builders/aggregates.txt

@@ -119,11 +119,11 @@ pipeline stage that returns literal documents from input values.
 
 .. important::
 
-   If you use a ``$documents`` stage in an aggregation pipeline, it must be the first 
+   If you use a ``$documents`` stage in an aggregation pipeline, it must be the first
    stage in the pipeline.
 
-The following example creates a pipeline stage that creates 
-sample documents with a ``title`` field: 
+The following example creates a pipeline stage that creates
+sample documents with a ``title`` field:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java
    :start-after: // begin documents
@@ -133,8 +133,8 @@ sample documents with a ``title`` field:
 
 .. important::
 
-   If you use the ``documents()`` method to provide the input to an aggregation pipeline, 
-   you must call the ``aggregate()`` method on a database instead of on a 
+   If you use the ``documents()`` method to provide the input to an aggregation pipeline,
+   you must call the ``aggregate()`` method on a database instead of on a
    collection.
 
 
@@ -975,3 +975,40 @@ 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)>`__.
 
+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 how set these up in MongoDB Atlas, 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 from 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,long)>`__ API documentation.

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

@@ -6,6 +6,8 @@
 import static com.mongodb.client.model.Projections.*;
 import static com.mongodb.client.model.Sorts.*;
 import static com.mongodb.client.model.Accumulators.*;
+import static com.mongodb.client.model.search.SearchPath.fieldPath;
+import static com.mongodb.client.model.search.VectorSearchOptions.vectorSearchOptions;
 import static java.util.Arrays.asList;
 // end static import
 
@@ -16,8 +18,10 @@
 import com.mongodb.client.MongoCursor;
 import com.mongodb.client.MongoDatabase;
 import com.mongodb.client.model.*;
-
+import com.mongodb.client.model.search.VectorSearchOptions;
 import java.util.List;
+import com.mongodb.client.model.search.FieldSearchPath;
+import org.bson.BsonString;
 import org.bson.Document;
 import org.bson.conversions.Bson;
 
@@ -27,7 +31,7 @@ public class AggBuilders {
     private MongoDatabase database;
 
     private AggBuilders() {
-        final String uri = System.getenv("DRIVER_REF_SRV");
+        final String uri = "<Your connection string>";
 
         mongoClient = MongoClients.create(uri);
         database = mongoClient.getDatabase("sample_mflix");
@@ -77,7 +81,9 @@ public static void main(String[] args) {
         page.basicBucketAutoStage();
         page.bucketAutoOptionsStage();
         page.facetStage();
-        page.setWindowFieldsStage();
+        page.vectorSearchPipeline();
+// Fix required: https://jira.mongodb.org/browse/DOCSP-33327
+//        page.setWindowFieldsStage();
         page.aggregationExample();
     }
 
@@ -89,6 +95,7 @@ private void aggregationExample() {
         // end aggregationSample
     }
 
+    /* Fix required: https://jira.mongodb.org/browse/DOCSP-33327
     private void setWindowFieldsStage() {
         // begin setWindowFields
         Window pastMonth = Windows.timeRange(-1, MongoTimeUnit.MONTH, Windows.Bound.CURRENT);
@@ -97,6 +104,7 @@ private void setWindowFieldsStage() {
                 WindowedComputations.avg("monthlyAvgTemp", "$temperature", pastMonth));
         // end setWindowFields
     }
+     */
 
     private void facetStage() {
         // begin facet
@@ -247,12 +255,13 @@ private void advancedLookupStage() {
                                 new Document("$gte", asList("$instock", "$$order_qty")))))),
                 project(fields(exclude("stock_item"), excludeId())));
 
-        List<Bson> innerJoinLookup = lookup("warehouses", variables, pipeline, "stockdata");
+        Bson innerJoinLookup = lookup("warehouses", variables, pipeline, "stockdata");
         // end advanced lookup
-        MongoCursor<Document> cursor = collection.aggregate(asList(advancedLookup)).cursor();
-        cursor.forEachRemaining(doc -> System.out.println(doc.toJson()));
-        database = mongoClient.getDatabase("sample_mflix");
-        collection = database.getCollection("movies");
+        // Missing advancedLookup assignment
+//        MongoCursor<Document> cursor = collection.aggregate(asList(advancedLookup)).cursor();
+//        cursor.forEachRemaining(doc -> System.out.println(doc.toJson()));
+//        database = mongoClient.getDatabase("sample_mflix");
+//        collection = database.getCollection("movies");
     }
 
     private void basicLookupStage() {
@@ -303,7 +312,41 @@ private void matchStage() {
         // end match
     }
 
-    private void documents() {
+    // Requires MongoDB version that supports $vectorSearch
+    private void vectorSearchPipeline() {
+
+        // begin vectorSearch
+        List<Double> queryVector = (asList(-0.0072121937, -0.030757688, -0.012945653));
+        String indexName = "mflix_movies_embedding_index";
+        FieldSearchPath fieldSearchPath = fieldPath("plot_embedding");
+        int numCandidates = 2;
+        int limit = 1;
+        VectorSearchOptions options = vectorSearchOptions().filter(gte("year", 2016));
+
+        List<Bson> pipeline = asList(
+                vectorSearch(
+                        fieldSearchPath,
+                        queryVector,
+                        indexName,
+                        numCandidates,
+                        limit,
+                        options),
+                project(
+                    metaVectorSearchScore("vectorSearchScore")));
+        // end vectorSearch
+
+        // begin vectorSearch-output
+        Document found = collection.aggregate(pipeline).first();
+        double score = found.getDouble("vectorSearchScore").doubleValue();
+
+        System.out.println("vectorSearch score: " + score);
+        // end vectorSearch-output
+
+        // Example output: "vectorSearch score: 0.887437105178833"
+    }
+
+
+    private void documentsStage() {
         // begin documents
         documents(asList(
                 new Document("title", "The Shawshank Redemption"),