Add phrase operator for Atlas Search (#1586)

Add phrase operator for Atlas Search

There are several Atlas Search query operators that are not implemented with first class support in the Java driver. This PR adds the phrase operator to Atlas Search.

JAVA-5724

Author: joykim1005

Diff for: driver-core/src/main/com/mongodb/client/model/search/PhraseConstructibleBsonElement.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.mongodb.client.model.search;
+
+import com.mongodb.internal.client.model.AbstractConstructibleBsonElement;
+
+import org.bson.conversions.Bson;
+
+import static com.mongodb.assertions.Assertions.notNull;
+
+final class PhraseConstructibleBsonElement extends AbstractConstructibleBsonElement<PhraseConstructibleBsonElement> implements
+        PhraseSearchOperator {
+    PhraseConstructibleBsonElement(final String name, final Bson value) {
+        super(name, value);
+    }
+
+    private PhraseConstructibleBsonElement(final Bson baseElement, final Bson appendedElementValue) {
+        super(baseElement, appendedElementValue);
+    }
+
+    @Override
+    protected PhraseConstructibleBsonElement newSelf(final Bson baseElement, final Bson appendedElementValue) {
+        return new PhraseConstructibleBsonElement(baseElement, appendedElementValue);
+    }
+
+    @Override
+    public PhraseSearchOperator synonyms(final String name) {
+        return newWithAppendedValue("synonyms", notNull("name", name));
+    }
+
+    @Override
+    public PhraseSearchOperator slop(final int slop) {
+        return newWithAppendedValue("slop", slop);
+    }
+
+    @Override
+    public PhraseConstructibleBsonElement score(final SearchScore modifier) {
+        return newWithAppendedValue("score", notNull("modifier", modifier));
+    }
+}

Diff for: driver-core/src/main/com/mongodb/client/model/search/PhraseSearchOperator.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.mongodb.client.model.search;
+
+import com.mongodb.annotations.Beta;
+import com.mongodb.annotations.Reason;
+import com.mongodb.annotations.Sealed;
+
+/**
+ * @see SearchOperator#phrase(SearchPath, String)
+ * @see SearchOperator#phrase(Iterable, Iterable)
+ * @since 5.3
+ */
+
+@Sealed
+@Beta(Reason.CLIENT)
+public interface PhraseSearchOperator extends SearchOperator {
+    @Override
+    PhraseSearchOperator score(SearchScore modifier);
+
+    /**
+     * Creates a new {@link PhraseSearchOperator} that uses slop. The default value is 0.
+     *
+     * @param slop The allowable distance between words in the query phrase.
+     * @return A new {@link PhraseSearchOperator}.
+     */
+    PhraseSearchOperator slop(int slop);
+
+    /**
+     * Creates a new {@link PhraseSearchOperator} that uses synonyms.
+     *
+     * @param name The name of the synonym mapping.
+     * @return A new {@link PhraseSearchOperator}.
+     *
+     * @mongodb.atlas.manual atlas-search/synonyms/ Synonym mappings
+     */
+    PhraseSearchOperator synonyms(String name);
+}

Diff for: driver-core/src/main/com/mongodb/client/model/search/SearchOperator.java

@@ -292,6 +292,36 @@ static GeoNearSearchOperator near(final Point origin, final Number pivot, final
                 .append("pivot", notNull("pivot", pivot)));
     }
 
+    /**
+     * Returns a {@link SearchOperator} that performs a search for documents containing an ordered sequence of terms.
+     *
+     * @param path The field to be searched.
+     * @param query The string to search for.
+     * @return The requested {@link SearchOperator}.
+     * @mongodb.atlas.manual atlas-search/phrase/ phrase operator
+     */
+    static PhraseSearchOperator phrase(final SearchPath path, final String query) {
+        return phrase(singleton(notNull("path", path)), singleton(notNull("query", query)));
+    }
+
+    /**
+     * Returns a {@link SearchOperator} that performs a search for documents containing an ordered sequence of terms.
+     *
+     * @param paths The non-empty fields to be searched.
+     * @param queries The non-empty strings to search for.
+     * @return The requested {@link SearchOperator}.
+     * @mongodb.atlas.manual atlas-search/phrase/ phrase operator
+     */
+    static PhraseSearchOperator phrase(final Iterable<? extends SearchPath> paths, final Iterable<String> queries) {
+        Iterator<? extends SearchPath> pathIterator = notNull("paths", paths).iterator();
+        isTrueArgument("paths must not be empty", pathIterator.hasNext());
+        Iterator<String> queryIterator = notNull("queries", queries).iterator();
+        isTrueArgument("queries must not be empty", queryIterator.hasNext());
+        String firstQuery = queryIterator.next();
+        return new PhraseConstructibleBsonElement("phrase", new Document("path", combineToBsonValue(pathIterator, false))
+                .append("query", queryIterator.hasNext() ? queries : firstQuery));
+    }
+
     /**
      * Creates a {@link SearchOperator} from a {@link Bson} in situations when there is no builder method that better satisfies your needs.
      * This method cannot be used to validate the syntax.

Diff for: driver-core/src/test/functional/com/mongodb/client/model/search/AggregatesSearchIntegrationTest.java

@@ -82,6 +82,7 @@
 import static com.mongodb.client.model.search.SearchOperator.exists;
 import static com.mongodb.client.model.search.SearchOperator.near;
 import static com.mongodb.client.model.search.SearchOperator.numberRange;
+import static com.mongodb.client.model.search.SearchOperator.phrase;
 import static com.mongodb.client.model.search.SearchOperator.text;
 import static com.mongodb.client.model.search.SearchOptions.searchOptions;
 import static com.mongodb.client.model.search.SearchPath.fieldPath;
@@ -608,7 +609,8 @@ private static Stream<Arguments> searchAndSearchMetaArgs() {
                                         dateRange(fieldPath("fieldName6"))
                                                 .lte(Instant.ofEpochMilli(1)),
                                         near(0, 1.5, fieldPath("fieldName7"), fieldPath("fieldName8")),
-                                        near(Instant.ofEpochMilli(1), Duration.ofMillis(3), fieldPath("fieldName9"))
+                                        near(Instant.ofEpochMilli(1), Duration.ofMillis(3), fieldPath("fieldName9")),
+                                        phrase(fieldPath("fieldName10"), "term6")
                                 ))
                                 .minimumShouldMatch(1)
                                 .mustNot(singleton(

Diff for: driver-core/src/test/unit/com/mongodb/client/model/search/SearchOperatorTest.java

@@ -581,6 +581,74 @@ void near() {
         );
     }
 
+    @Test
+    void phrase() {
+        assertAll(
+                () -> assertThrows(IllegalArgumentException.class, () ->
+                        // queries must not be empty
+                        SearchOperator.phrase(singleton(fieldPath("fieldName")), emptyList())
+                ),
+                () -> assertThrows(IllegalArgumentException.class, () ->
+                        // paths must not be empty
+                        SearchOperator.phrase(emptyList(), singleton("term"))
+                ),
+                () -> assertEquals(
+                        new BsonDocument("phrase",
+                                new BsonDocument("path", fieldPath("fieldName").toBsonValue())
+                                        .append("query", new BsonString("term"))
+                        ),
+                        SearchOperator.phrase(
+                                fieldPath("fieldName"),
+                                "term")
+                                .toBsonDocument()
+                ),
+                () -> assertEquals(
+                        new BsonDocument("phrase",
+                                new BsonDocument("path", new BsonArray(asList(
+                                        fieldPath("fieldName").toBsonValue(),
+                                        wildcardPath("wildc*rd").toBsonValue())))
+                                        .append("query", new BsonArray(asList(
+                                                new BsonString("term1"),
+                                                new BsonString("term2"))))
+                        ),
+                        SearchOperator.phrase(
+                                        asList(
+                                                fieldPath("fieldName"),
+                                                wildcardPath("wildc*rd")),
+                                        asList(
+                                                "term1",
+                                                "term2"))
+                                .toBsonDocument()
+                ),
+                () -> assertEquals(
+                        new BsonDocument("phrase",
+                                new BsonDocument("path", fieldPath("fieldName").toBsonValue())
+                                        .append("query", new BsonString("term"))
+                                        .append("synonyms", new BsonString("synonymMappingName"))
+                        ),
+                        SearchOperator.phrase(
+                                singleton(fieldPath("fieldName")),
+                                singleton("term"))
+                                .synonyms("synonymMappingName")
+                                .toBsonDocument()
+                ),
+                () -> assertEquals(
+                        new BsonDocument("phrase",
+                                new BsonDocument("path", fieldPath("fieldName").toBsonValue())
+                                        .append("query", new BsonString("term"))
+                                        .append("synonyms", new BsonString("synonymMappingName"))
+                                        .append("slop", new BsonInt32(5))
+                        ),
+                        SearchOperator.phrase(
+                                singleton(fieldPath("fieldName")),
+                                singleton("term"))
+                                .synonyms("synonymMappingName")
+                                .slop(5)
+                                .toBsonDocument()
+                )
+        );
+    }
+
     private static SearchOperator docExamplePredefined() {
         return SearchOperator.exists(
                 fieldPath("fieldName"));

Diff for: driver-scala/src/main/scala/org/mongodb/scala/model/search/SearchOperator.scala

@@ -228,6 +228,27 @@ object SearchOperator {
   def near(origin: Point, pivot: Number, paths: Iterable[_ <: FieldSearchPath]): GeoNearSearchOperator =
     JSearchOperator.near(origin, pivot, paths.asJava)
 
+  /**
+   * Returns a `SearchOperator` that performs a search for documents containing an ordered sequence of terms.
+   *
+   * @param path The field to be searched.
+   * @param query The string to search for.
+   * @return The requested `SearchOperator`.
+   * @see [[https://www.mongodb.com/docs/atlas/atlas-search/phrase/ phrase operator]]
+   */
+  def phrase(path: SearchPath, query: String): PhraseSearchOperator = JSearchOperator.phrase(path, query)
+
+  /**
+   * Returns a `SearchOperator` that performs a search for documents containing an ordered sequence of terms.
+   *
+   * @param paths The non-empty fields to be searched.
+   * @param queries The non-empty strings to search for.
+   * @return The requested `SearchOperator`.
+   * @see [[https://www.mongodb.com/docs/atlas/atlas-search/phrase/ phrase operator]]
+   */
+  def phrase(paths: Iterable[_ <: SearchPath], queries: Iterable[String]): PhraseSearchOperator =
+    JSearchOperator.phrase(paths.asJava, queries.asJava)
+
   /**
    * Creates a `SearchOperator` from a `Bson` in situations when there is no builder method that better satisfies your needs.
    * This method cannot be used to validate the syntax.

Diff for: driver-scala/src/main/scala/org/mongodb/scala/model/search/package.scala

@@ -119,6 +119,14 @@ package object search {
   @Beta(Array(Reason.CLIENT))
   type TextSearchOperator = com.mongodb.client.model.search.TextSearchOperator
 
+  /**
+   * @see `SearchOperator.phrase(String, SearchPath)`
+   * @see `SearchOperator.phrase(Iterable, Iterable)`
+   */
+  @Sealed
+  @Beta(Array(Reason.CLIENT))
+  type PhraseSearchOperator = com.mongodb.client.model.search.PhraseSearchOperator
+
   /**
    * @see `SearchOperator.autocomplete(String, FieldSearchPath)`
    * @see `SearchOperator.autocomplete(Iterable, FieldSearchPath)`