DOCSP-21671: Atlas Text Search Builder (#258)

* DOCSP-21671: Atlas Text Search Builder

Author: Chris Cho

source/fundamentals/builders/aggregates.txt

@@ -562,3 +562,29 @@ and ``temperature`` fields:
    :end-before: // end setWindowFields
    :language: java
    :dedent:
+
+Atlas Full-Text Search
+----------------------
+
+Use the ``search()`` method to create a :manual:`$search </reference/operator/aggregation/search/>`
+pipeline stage that specifies a full-text search of one or more fields.
+
+.. tip:: Only Available on Atlas for MongoDB v4.2 and later
+
+   This aggregation pipeline operator is only available for collections hosted
+   on :atlas:`MongoDB Atlas </>` clusters running v4.2 or later that are
+   covered by an :atlas:`Atlas search index </reference/atlas-search/index-definitions/>`.
+   Learn more about the required setup and the functionality of this operator
+   from the :ref:`Atlas Search <fts-top-ref>` documentation.
+
+The following example creates a pipeline stage that searches the ``title``
+field for text that contains the word "Future":
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
+   :start-after: // begin atlasTextSearch
+   :end-before: // end atlasTextSearch
+   :language: java
+   :dedent:
+
+Learn more about the builders from the
+`search package API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/package-summary.html>`__.

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

@@ -0,0 +1,66 @@
+package fundamentals.builders;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.bson.Document;
+import org.bson.conversions.Bson;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.MongoDatabase;
+import com.mongodb.client.model.Aggregates;
+import com.mongodb.client.model.Filters;
+import com.mongodb.client.model.Projections;
+import com.mongodb.client.model.search.SearchOperator;
+import com.mongodb.client.model.search.SearchPath;
+public class AggregateSearchBuilderExample {
+
+    private static final String CONNECTION_URI = "<connection URI>";
+
+    // Match aggregation
+    private static void runMatch(MongoCollection<Document> collection) {
+        Bson matchStage = Aggregates.match(Filters.eq("title", "Future"));
+        Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released")));
+
+        List<Bson> aggregateStages = Arrays.asList(matchStage, projection);
+        System.out.println("aggregateStages: " + aggregateStages);
+        collection.aggregate(
+                aggregateStages
+                ).forEach(result -> System.out.println(result));
+    }
+
+    /* 
+     * Atlas text search aggregation
+     * Requires Atlas cluster and full text search index
+     * See https://www.mongodb.com/docs/atlas/atlas-search/tutorial/ for more info on requirements
+     */
+    private static void runAtlasTextSearch(MongoCollection<Document> collection) {
+        // begin atlasTextSearch
+        Bson textSearch = Aggregates.search(
+                SearchOperator.text(
+                        SearchPath.fieldPath("title"), "Future"));
+        // end atlasTextSearch
+
+        Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released")));
+
+        List<Bson> aggregateStages = Arrays.asList(textSearch, projection);
+        System.out.println("aggregateStages: " + aggregateStages);
+
+        System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain());
+        collection.aggregate(aggregateStages).forEach(result -> System.out.println(result));
+    }
+
+    public static void main(String[] args) {
+        String uri = CONNECTION_URI; 
+
+        try (MongoClient mongoClient = MongoClients.create(uri)) {
+            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
+            MongoCollection<Document> collection = database.getCollection("movies");
+
+            // runMatch(collection);
+            runAtlasTextSearch(collection);
+        }
+    }
+}