[Java Sync] Add additional SearchOperator helper methods for the rest of the Atlas Search operators (mongodb#658)

rachel-mack · rustagir · rachel-mack · commit 340b9240e1cb · 2025-04-02T12:34:16.000-04:00
* atlas search operators

* aggregation page

* formatting

* table format

* references

* JS feedback

* use shared doc

* fix for new core-api variable

* eg updates

* rebase

* eg format

* format

* release reference

* WIP

* use List.of()

---------

Co-authored-by: rustagir &lt;rea.rustagi@mongodb.com&gt;
diff --git a/source/atlas-search.txt b/source/atlas-search.txt
@@ -30,23 +30,28 @@ search and which fields to index.
 Sample Data
 ~~~~~~~~~~~
 
-The example in this guide uses the ``movies`` collection in the ``sample_mflix``
+The examples in this guide use the ``movies`` collection in the ``sample_mflix``
 database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to
 create a free MongoDB Atlas cluster and load the sample datasets, see the
-:atlas:`Get Started with Atlas </getting-started>` guide.
+:atlas:`Get Started with Atlas </getting-started>` guide. To learn more about
+aggregation operations and builders, see the :ref:`java-aggregation` guide. 
 
 Run an Atlas Search Query
 -------------------------
 
 This section shows how to create an aggregation pipeline to run an
 Atlas Search query on a collection. You can use the ``Aggregates.search()`` builder
 method to create a ``$search`` pipeline stage, which specifies the search
-criteria. Then, call the ``aggregate()`` method and pass your pipeline as a parameter.
+criteria. Then, call the ``aggregate()`` method and pass your pipeline as a
+parameter.
 
-.. tip:: 
+.. note:: Only Available on Atlas for MongoDB v4.2 and later
 
-   To learn more about aggregation operations and builders, see the :ref:`java-aggregation`
-   guide. 
+   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 <java-atlas-search>` documentation.
 
 Before running an Atlas Search query, you must create an Atlas Search index
 on your collection. To learn how to programmatically create an Atlas Search
@@ -90,6 +95,60 @@ following actions:
    Search queries, see :atlas:`Atlas Search Tutorials </atlas-search/tutorials/>`
    in the Atlas documentation.
 
+Atlas Search Metadata
+---------------------
+
+Use the ``searchMeta()`` method to create a :manual:`$searchMeta
+</reference/operator/aggregation/searchMeta/>` pipeline stage, which returns
+only the metadata from of the Atlas full-text search results. 
+
+.. tip:: Only Available on Atlas for MongoDB v4.4.11 and later
+
+   This aggregation pipeline operator is available only
+   on :atlas:`MongoDB Atlas </>` clusters running v4.4.11 and later. For a
+   detailed list of version availability, see the MongoDB Atlas documentation
+   on :atlas:`$searchMeta </atlas-search/query-syntax/#-searchmeta>`.
+
+The following example shows the ``near`` metadata for an Atlas search
+aggregation stage:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
+   :start-after: // begin atlasSearchMeta
+   :end-before: // end atlasSearchMeta
+   :language: java
+   :dedent:
+
+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-search-helpers:
+
+Create Pipeline Search Stages
+-----------------------------
+
+.. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst
+
+   .. replacement:: as-idx-link
+
+      the :ref:`java-search-indexes` section of the Indexes guide
+
+   .. replacement:: atlas-query-operators-example
+
+      .. io-code-block::
+
+         .. input:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
+            :language: java
+            :start-after: // begin atlasHelperMethods
+            :end-before: // end atlasHelperMethods
+            :dedent:
+
+         .. output::
+            :language: console
+            :visible: false
+            
+            {"_id": ..., "genres": ["Comedy", "Romance"], "title": "Love at First Bite", "year": 1979}
+            {"_id": ..., "genres": ["Comedy", "Drama"], "title": "Love Affair", "year": 1994}
+
 Additional Information
 ----------------------
 
@@ -105,3 +164,4 @@ the following API documentation:
 - `MongoCollection.aggregate() <{+driver-api+}/MongoCollection.html#aggregate(java.util.List)>`__
 - `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__
 - `Aggregates.project() <{+core-api+}/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__
+- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__
diff --git a/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java b/source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
@@ -1,6 +1,5 @@
-package fundamentals.builders;
+package org.example;
 
-import java.util.Arrays;
 import java.util.List;
 
 import org.bson.Document;
@@ -14,7 +13,8 @@
 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;
+import static com.mongodb.client.model.search.SearchPath.fieldPath;
+
 public class AggregateSearchBuilderExample {
 
     private static final String CONNECTION_URI = "<connection URI>";
@@ -24,14 +24,14 @@ 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);
+        List<Bson> aggregateStages = List.of(matchStage, projection);
         System.out.println("aggregateStages: " + aggregateStages);
         collection.aggregate(
                 aggregateStages
-                ).forEach(result -> System.out.println(result));
+        ).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
@@ -40,13 +40,65 @@ private static void runAtlasTextSearch(MongoCollection<Document> collection) {
         // begin atlasTextSearch
         Bson textSearch = Aggregates.search(
                 SearchOperator.text(
-                        SearchPath.fieldPath("title"), "Future"));
+                        fieldPath("title"), "Future"));
         // end atlasTextSearch
 
         // To condense result data, add this projection into the pipeline
         // Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released")));
 
-        List<Bson> aggregateStages = Arrays.asList(textSearch);
+        List<Bson> aggregateStages = List.of(textSearch);
+        System.out.println("aggregateStages: " + aggregateStages);
+
+        System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain());
+        collection.aggregate(aggregateStages).forEach(result -> System.out.println(result));
+    }
+
+    /*
+     * Atlas 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 runAtlasSearchWithSearchHelperMethods(MongoCollection<Document> collection) {
+        // begin atlasHelperMethods
+        List<Bson> pipeline = new ArrayList<>();
+
+        pipeline.add(Aggregates.search(
+                SearchOperator.compound()
+                        .filter(
+                                List.of(
+                                        SearchOperator.in(fieldPath("genres"), "Comedy"),
+                                        SearchOperator.phrase(fieldPath("fullplot"), "new york"),
+                                        SearchOperator.numberRange(fieldPath("year")).gtLt(1950, 2000),
+                                        SearchOperator.wildcard(fieldPath("title"), "Love *")
+                                ))));
+
+        pipeline.add(Aggregates.project(
+                Projections.include("title", "year", "genres")
+        ));
+
+        AggregateIterable<Document> results = collection.aggregate(pipeline);
+        results.forEach(doc -> System.out.println(doc.toJson()));
+        // end atlasHelperMethods
+    }
+
+    /*
+     * Atlas 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 runAtlasSearch(MongoCollection<Document> collection) {
+        // begin atlasSearch
+        Bson search_stage = Aggregates.search(
+                SearchOperator.compound()
+                        .filter(List.of(SearchOperator.text(fieldPath("genres"), "Drama")))
+                        .must(List.of(SearchOperator.phrase(fieldPath("cast"), "keanu reeves")))
+        );
+        // end atlasSearch
+
+        // To condense result data, add this projection into the pipeline
+        // Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released")));
+
+        List<Bson> aggregateStages = List.of(search_stage);
         System.out.println("aggregateStages: " + aggregateStages);
 
         System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain());
@@ -55,12 +107,12 @@ private static void runAtlasTextSearch(MongoCollection<Document> collection) {
 
     private static void runAtlasTextSearchMeta(MongoCollection<Document> collection) {
         Bson textSearchMeta =
-        // begin atlasSearchMeta
-        Aggregates.searchMeta(
-                SearchOperator.near(2010, 1, SearchPath.fieldPath("year")));
+                // begin atlasSearchMeta
+                Aggregates.searchMeta(
+                        SearchOperator.near(2010, 1, fieldPath("year")));
         // end atlasSearchMeta
 
-        List<Bson> aggregateStages = Arrays.asList(textSearchMeta);
+        List<Bson> aggregateStages = List.of(textSearchMeta);
         System.out.println("aggregateStages: " + aggregateStages);
 
         collection.aggregate(aggregateStages).forEach(result -> System.out.println(result));
@@ -77,7 +129,9 @@ public static void main(String[] args) {
             // Uncomment the methods that correspond to what you're testing
             // runMatch(collection);
             // runAtlasTextSearch(collection);
-            runAtlasTextSearchMeta(collection);
+            // runAtlasSearch(collection);
+            // runAtlasTextSearchMeta(collection);
+            // runAtlasSearchWithSearchHelperMethods(collection);
         }
     }
 }
diff --git a/source/references/whats-new.txt b/source/references/whats-new.txt
@@ -54,7 +54,7 @@ and features:
 
    .. replacement:: atlas-query-operators
 
-      the :ref:`java-atlas-search` guide
+      the :ref:`java-atlas-search-helpers` section of the Atlas Search guide
 
 .. _java-version-5.3:
 
