[Backport v5.4] [Java RS] Add additional SearchOperator helper methods for the rest of the Atlas Search operators (#123)

Co-authored-by: Rachel Mackintosh <[email protected]>

Author: github-actions[bot]

.DS_Store

@@ -124,3 +124,81 @@ To ``$explain`` an aggregation pipeline, call the
            Aggregates.group("$stars", Accumulators.sum("count", 1))))
        .explain()
        .subscribe(new PrintDocumentSubscriber());
+
+.. _java-rs-atlas-search-stage:
+
+Atlas Search
+------------
+
+You can perform an :atlas:`Atlas Search </atlas-search>` query by creating and running
+an aggregation pipeline that contains one of the following pipeline stages: 
+
+- ``$search``
+- ``$searchMeta``
+
+The {+driver-short+} provides the `Aggregates.search()
+<{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchOperator)>`__
+and `Aggregates.searchMeta()
+<{+core-api+}/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchOperator)>`__
+methods to perform Atlas Search queries.
+
+To learn more about Atlas Search pipeline stages, see :atlas:`Choose the
+Aggregation Pipeline Stage </atlas-search/query-syntax/>` in the Atlas
+documentation.
+
+Create Pipeline Search Stages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create the search criteria in your Atlas Search pipeline stage
+by using Search operators.
+
+.. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst
+
+   .. replacement:: as-idx-link
+
+      the :ref:`java-rs-atlas-search-idx-mgmt` section of the Indexes guide
+
+   .. replacement:: atlas-query-operators-example
+
+      .. io-code-block::
+
+         .. input:: /includes/aggregation/atlas-search-examples.java
+            :language: java
+            :start-after: // start 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
+----------------------
+
+To view a full list of expression operators, see :manual:`Aggregation
+Operators </reference/operator/aggregation/>` in the {+mdb-server+} manual.
+
+To learn about assembling an aggregation pipeline and view examples, see
+:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` in the {+mdb-server+} manual.
+
+To learn more about creating pipeline stages, see :manual:`Aggregation
+Stages </reference/operator/aggregation-pipeline/>` in the {+mdb-server+} manual.
+
+To learn more about explaining MongoDB operations, see
+:manual:`Explain Output </reference/explain-results/>` and
+:manual:`Query Plans </core/query-plans/>` in the {+mdb-server+} manual.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the classes and methods mentioned in this guide, see
+the following API documentation:
+
+- `aggregate() <{+driver-api+}/MongoCollection.html#aggregate(java.util.List)>`__
+- `Aggregates <{+core-api+}/client/model/Aggregates.html>`__
+- `AggregatePublisher <{+driver-api+}/AggregatePublisher.html>`__
+- `search() <{+core-api+}/client/model/Aggregates#search(com.mongodb.client.model.search.SearchOperator)>`__
+- `project() <{+core-api+}/client/model/Aggregates#project(org.bson.conversions.Bson)>`__

source/aggregation.txt

@@ -0,0 +1,54 @@
+package org.example;
+
+import com.mongodb.*;
+import com.mongodb.client.model.Projections;
+import com.mongodb.reactivestreams.client.*;
+import org.bson.Document;
+
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+
+import org.bson.conversions.Bson;
+
+import com.mongodb.client.model.Aggregates;
+import com.mongodb.client.model.search.SearchOperator;
+
+import static com.mongodb.client.model.search.SearchPath.fieldPath;
+
+import org.reactivestreams.Publisher;
+
+public class SearchHelpers {
+    public static void main(String[] args) {
+        // Replace the placeholder with your Atlas connection string
+        String uri = "<connection string>";
+
+        // Create a new client and connect to the server
+        try (MongoClient mongoClient = MongoClients.create(uri)) {
+            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
+            MongoCollection<Document> movies = database.getCollection("movies");
+
+            // start atlasHelperMethods
+            Bson searchStageFilters = Aggregates.search(
+                    SearchOperator.compound()
+                            .filter(
+                                    List.of(
+                                            SearchOperator.in(fieldPath("genres"), List.of("Comedy")),
+                                            SearchOperator.phrase(fieldPath("fullplot"), "new york"),
+                                            SearchOperator.numberRange(fieldPath("year")).gtLt(1950, 2000),
+                                            SearchOperator.wildcard(fieldPath("title"), "Love *")
+                                    )));
+
+            Bson projection = Aggregates.project(Projections.fields(
+                    Projections.include("title", "year", "genres")
+            ));
+
+            List<Bson> aggregateStages = List.of(searchStageFilters, projection);
+
+            Publisher<Document> publisher = movies.aggregate(aggregateStages);
+            publisher.subscribe(new SubscriberHelpers.PrintDocumentSubscriber());
+            Mono.from(publisher).block();
+            // end atlasHelperMethods
+        }
+    }
+}

source/includes/aggregation/atlas-search-examples.java

@@ -177,6 +177,8 @@ field:
 .. TODO: To learn more about wildcard indexes, see the :ref:`java-rs-clustered-index`
 .. guide.
 
+.. _java-rs-atlas-search-idx-mgmt:
+
 Atlas Search Index Management
 -----------------------------
 
@@ -275,4 +277,4 @@ The following example deletes an index with the specified name:
    :dedent:
 
 .. TODO: To learn more about removing indexes, see :ref:`java-rs-indexes-remove`
-.. in the Work with Indexes guide.
+.. in the Work with Indexes guide.

source/indexes.txt

@@ -57,8 +57,8 @@ and features:
 
    .. replacement:: atlas-query-operators
 
-      the `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__
-      interface API documentation
+      the :ref:`java-rs-atlas-search-stage` section of the Aggregation
+      guide
 
 .. _javars-version-5.3: