CSHARP-5543: Add new options for Atlas Search Text and Phrase operators

src/MongoDB.Driver/MatchCriteria.cs

@@ -0,0 +1,32 @@
+/* Copyright 2010-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.
+ */
+
+namespace MongoDB.Driver
+{
+    /// <summary>
+    /// Represents the criteria used to match terms in a query for the Atlas Search Text operator.
+    /// </summary>
+    public enum MatchCriteria
+    {
+        /// <summary>
+        /// Match documents containing any of the terms from a query.
+        /// </summary>
+        Any,
+        /// <summary>
+        /// Match documents containing all the terms from a query.
+        /// </summary>
+        All
+    }
+}

src/MongoDB.Driver/Search/OperatorSearchDefinitions.cs

@@ -317,6 +317,7 @@ internal sealed class PhraseSearchDefinition<TDocument> : OperatorSearchDefiniti
     {
         private readonly SearchQueryDefinition _query;
         private readonly int? _slop;
+        private readonly string _synonyms;
 
         public PhraseSearchDefinition(
             SearchPathDefinition<TDocument> path,
@@ -329,11 +330,23 @@ public PhraseSearchDefinition(
             _slop = slop;
         }
 
+        public PhraseSearchDefinition(
+            SearchPathDefinition<TDocument> path,
+            SearchQueryDefinition query,
+            SearchPhraseOptions<TDocument> options)
+            : base(OperatorType.Phrase, path, options?.Score)
+        {
+            _query = Ensure.IsNotNull(query, nameof(query));
+            _slop = options?.Slop;
+            _synonyms = options?.Synonyms;
+        }
+
         private protected override BsonDocument RenderArguments(RenderArgs<TDocument> args) =>
             new()
             {
                 { "query", _query.Render() },
-                { "slop", _slop, _slop != null }
+                { "slop", _slop, _slop != null },
+                { "synonyms", _synonyms, _synonyms != null }
             };
     }
 
@@ -455,6 +468,7 @@ private protected override BsonDocument RenderArguments(RenderArgs<TDocument> ar
     internal sealed class TextSearchDefinition<TDocument> : OperatorSearchDefinition<TDocument>
     {
         private readonly SearchFuzzyOptions _fuzzy;
+        private readonly MatchCriteria? _matchCriteria;
         private readonly SearchQueryDefinition _query;
         private readonly string _synonyms;
 
@@ -471,12 +485,25 @@ public TextSearchDefinition(
             _synonyms = synonyms;
         }
 
+        public TextSearchDefinition(
+            SearchPathDefinition<TDocument> path,
+            SearchQueryDefinition query,
+            SearchTextOptions<TDocument> options)
+            : base(OperatorType.Text, path, options?.Score)
+        {
+            _query = Ensure.IsNotNull(query, nameof(query));
+            _fuzzy = options?.Fuzzy;
+            _synonyms = options?.Synonyms;
+            _matchCriteria = options?.MatchCriteria;
+        }
+
         private protected override BsonDocument RenderArguments(RenderArgs<TDocument> args) =>
             new()
             {
                 { "query", _query.Render() },
                 { "fuzzy", () => _fuzzy.Render(), _fuzzy != null },
-                { "synonyms", _synonyms, _synonyms != null }
+                { "synonyms", _synonyms, _synonyms != null },
+                { "matchCriteria", _matchCriteria == MatchCriteria.Any ? "any" : "all", _matchCriteria != null }
             };
     }
 

src/MongoDB.Driver/Search/SearchDefinitionBuilder.cs

@@ -552,6 +552,20 @@ public SearchDefinition<TDocument> Phrase(
             SearchScoreDefinition<TDocument> score = null) =>
                 new PhraseSearchDefinition<TDocument>(path, query, slop, score);
 
+        /// <summary>
+        /// Creates a search definition that performs search for documents containing an ordered
+        /// sequence of terms.
+        /// </summary>
+        /// <param name="path">The indexed field or fields to search.</param>
+        /// <param name="query">The string or strings to search for.</param>
+        /// <param name="options">The options.</param>
+        /// <returns>A phrase search definition.</returns>
+        public SearchDefinition<TDocument> Phrase(
+            SearchPathDefinition<TDocument> path,
+            SearchQueryDefinition query,
+            SearchPhraseOptions<TDocument> options) =>
+            new PhraseSearchDefinition<TDocument>(path, query, options);
+
         /// <summary>
         /// Creates a search definition that performs search for documents containing an ordered
         /// sequence of terms.
@@ -569,6 +583,21 @@ public SearchDefinition<TDocument> Phrase<TField>(
             SearchScoreDefinition<TDocument> score = null) =>
                 Phrase(new ExpressionFieldDefinition<TDocument>(path), query, slop, score);
 
+        /// <summary>
+        /// Creates a search definition that performs search for documents containing an ordered
+        /// sequence of terms.
+        /// </summary>
+        /// <typeparam name="TField">The type of the field.</typeparam>
+        /// <param name="path">The indexed field or fields to search.</param>
+        /// <param name="query">The string or strings to search for.</param>
+        /// <param name="options">The options.</param>
+        /// <returns>A phrase search definition.</returns>
+        public SearchDefinition<TDocument> Phrase<TField>(
+            Expression<Func<TDocument, TField>> path,
+            SearchQueryDefinition query,
+            SearchPhraseOptions<TDocument> options) =>
+            Phrase(new ExpressionFieldDefinition<TDocument>(path), query, options);
+
         /// <summary>
         /// Creates a search definition that queries a combination of indexed fields and values.
         /// </summary>
@@ -732,6 +761,20 @@ public SearchDefinition<TDocument> Regex<TField>(
         public SearchDefinition<TDocument> Span(SearchSpanDefinition<TDocument> clause) =>
             new SpanSearchDefinition<TDocument>(clause);
 
+        /// <summary>
+        /// Creates a search definition that performs full-text search using the analyzer specified
+        /// in the index configuration.
+        /// </summary>
+        /// <param name="path">The indexed field or fields to search.</param>
+        /// <param name="query">The string or strings to search for.</param>
+        /// <param name="options">The options.</param>
+        /// <returns>A text search definition.</returns>
+        public SearchDefinition<TDocument> Text(
+            SearchPathDefinition<TDocument> path,
+            SearchQueryDefinition query,
+            SearchTextOptions<TDocument> options) =>
+            new TextSearchDefinition<TDocument>(path, query, options);
+
         /// <summary>
         /// Creates a search definition that performs full-text search using the analyzer specified
         /// in the index configuration.
@@ -764,6 +807,21 @@ public SearchDefinition<TDocument> Text(
             SearchScoreDefinition<TDocument> score = null) =>
                 new TextSearchDefinition<TDocument>(path, query, null, score, synonyms);
 
+        /// <summary>
+        /// Creates a search definition that performs full-text search using the analyzer specified
+        /// in the index configuration.
+        /// </summary>
+        /// <typeparam name="TField">The type of the field.</typeparam>
+        /// <param name="path">The indexed field or field to search.</param>
+        /// <param name="query">The string or strings to search for.</param>
+        /// <param name="options">The options.</param>
+        /// <returns>A text search definition.</returns>
+        public SearchDefinition<TDocument> Text<TField>(
+            Expression<Func<TDocument, TField>> path,
+            SearchQueryDefinition query,
+            SearchTextOptions<TDocument> options) =>
+            Text(new ExpressionFieldDefinition<TDocument>(path), query, options);
+
         /// <summary>
         /// Creates a search definition that performs full-text search using the analyzer specified
         /// in the index configuration.

src/MongoDB.Driver/Search/SearchPhraseOptions.cs

@@ -0,0 +1,38 @@
+/* Copyright 2010-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.
+ */
+
+namespace MongoDB.Driver.Search
+{
+    /// <summary>
+    /// Options for atlas search phrase operator.
+    /// </summary>
+    public sealed class SearchPhraseOptions<TDocument>
+    {
+        /// <summary>
+        /// The score modifier.
+        /// </summary>
+        public SearchScoreDefinition<TDocument> Score { get; set; }
+
+        /// <summary>
+        /// The allowable distance between words in the query phrase.
+        /// </summary>
+        public int? Slop { get; set; }
+
+        /// <summary>
+        /// The name of the synonym mapping definition in the index definition. Value can't be an empty string.
+        /// </summary>
+        public string Synonyms { get; set; }
+    }
+}

src/MongoDB.Driver/Search/SearchTextOptions.cs

@@ -0,0 +1,44 @@
+/* Copyright 2010-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.
+ */
+
+namespace MongoDB.Driver.Search
+{
+    /// <summary>
+    /// Options for atlas search text operator.
+    /// </summary>
+    public sealed class SearchTextOptions<TDocument>
+    {
+        /// <summary>
+        /// The options for fuzzy search.
+        /// </summary>
+        public SearchFuzzyOptions Fuzzy { get; set; }
+
+        /// <summary>
+        /// The criteria to use to match the terms in the query. Value can be either "any" or "all".
+        /// Defaults to "all" if omitted.
+        /// </summary>
+        public MatchCriteria MatchCriteria { get; set; }
+
+        /// <summary>
+        /// The score modifier.
+        /// </summary>
+        public SearchScoreDefinition<TDocument> Score { get; set; }
+
+        /// <summary>
+        /// The name of the synonym mapping definition in the index definition. Value can't be an empty string.
+        /// </summary>
+        public string Synonyms { get; set; }
+    }
+}

tests/MongoDB.Driver.Tests/Search/AtlasSearchTests.cs

@@ -421,6 +421,26 @@ public void PhraseAnalyzerPath()
             result.Title.Should().Be("Declaration of Independence");
         }
 
+        [Fact]
+        public void PhraseSynonym()
+        {
+            var result =
+                GetSynonymTestCollection().Aggregate()
+                    .Search(
+                        Builders<Movie>.Search.Phrase("plot", "automobile race", new SearchPhraseOptions<Movie> { Synonyms = "transportSynonyms" }),
+                        indexName: "synonyms-tests")
+                    .Project<Movie>(Builders<Movie>.Projection.Include("Title").Exclude("_id"))
+                    .Limit(5)
+                    .ToList();
+
+            result.Count.Should().Be(5);
+            result[0].Title.Should().Be("The Great Race");
+            result[1].Title.Should().Be("The Cannonball Run");
+            result[2].Title.Should().Be("National Mechanics");
+            result[3].Title.Should().Be("Genevieve");
+            result[4].Title.Should().Be("Speedway Junky");
+        }
+
         [Fact]
         public void PhraseWildcardPath()
         {
@@ -723,6 +743,26 @@ public void Text()
             result.Title.Should().Be("Declaration of Independence");
         }
 
+        [Fact]
+        public void TextMatchCriteria()
+        {
+            var result =
+                GetSynonymTestCollection().Aggregate()
+                    .Search(
+                        Builders<Movie>.Search.Text("plot", "attire", new SearchTextOptions<Movie> { Synonyms = "attireSynonyms", MatchCriteria = MatchCriteria.Any}),
+                        indexName: "synonyms-tests")
+                    .Project<Movie>(Builders<Movie>.Projection.Include("Title").Exclude("_id"))
+                    .Limit(5)
+                    .ToList();
+
+            result.Count.Should().Be(5);
+            result[0].Title.Should().Be("The Royal Tailor");
+            result[1].Title.Should().Be("La guerre des tuques");
+            result[2].Title.Should().Be("The Dress");
+            result[3].Title.Should().Be("The Club");
+            result[4].Title.Should().Be("The Triple Echo");
+        }
+
         [Theory]
         [InlineData("automobile", "transportSynonyms", "Blue Car")]
         [InlineData("boat", "transportSynonyms", "And the Ship Sails On")]

tests/MongoDB.Driver.Tests/Search/SearchDefinitionBuilderTests.cs

@@ -770,10 +770,22 @@ public void Phrase()
                 subject.Phrase("x", "foo", 5),
                 "{ phrase: { query: 'foo', path: 'x', slop: 5 } }");
 
+            AssertRendered(
+                subject.Phrase("x", "foo", new SearchPhraseOptions<BsonDocument> { Synonyms = "testSynonyms" }),
+                "{ phrase: { query: 'foo', path: 'x', synonyms: 'testSynonyms' } }");
+
+            AssertRendered(
+                subject.Phrase("x", "foo", 5),
+                "{ phrase: { query: 'foo', path: 'x', slop: 5 } }");
+
             var scoreBuilder = new SearchScoreDefinitionBuilder<BsonDocument>();
             AssertRendered(
                 subject.Phrase("x", "foo", score: scoreBuilder.Constant(1)),
                 "{ phrase: { query: 'foo', path: 'x', score: { constant: { value: 1 } } } }");
+
+            AssertRendered(
+                subject.Phrase("x", "foo", new SearchPhraseOptions<BsonDocument> { Score = scoreBuilder.Constant(1), Slop = 5}),
+                "{ phrase: { query: 'foo', slop: 5, path: 'x', score: { constant: { value: 1 } } } }");
         }
 
         [Fact]
@@ -791,6 +803,10 @@ public void Phrase_typed()
                 subject.Phrase(x => x.Hobbies, "foo"),
                 "{ phrase: { query: 'foo', path: 'hobbies' } }");
 
+            AssertRendered(
+                subject.Phrase(x => x.FirstName, "foo", new SearchPhraseOptions<Person> { Synonyms = "testSynonyms" }),
+                "{ phrase: { query: 'foo', synonyms: 'testSynonyms', path: 'fn' } }");
+
             AssertRendered(
                 subject.Phrase(
                     new FieldDefinition<Person>[]
@@ -1076,6 +1092,10 @@ public void Text()
                 subject.Text(new[] { "x", "y" }, new[] { "foo", "bar" }, "testSynonyms"),
                 "{ text: { query: ['foo', 'bar'], synonyms: 'testSynonyms', path: ['x', 'y'] } }");
 
+            AssertRendered(
+                subject.Text(new[] { "x", "y" }, new[] { "foo", "bar" }, new SearchTextOptions<BsonDocument>{ MatchCriteria = MatchCriteria.Any }),
+                "{ text: { query: ['foo', 'bar'], matchCriteria: 'any', path: ['x', 'y'] } }");
+
             AssertRendered(
                 subject.Text("x", "foo", new SearchFuzzyOptions()),
                 "{ text: { query: 'foo', path: 'x', fuzzy: {} } }");
@@ -1095,6 +1115,10 @@ public void Text()
             AssertRendered(
                 subject.Text("x", "foo", "testSynonyms", scoreBuilder.Constant(1)),
                 "{ text: { query: 'foo', synonyms: 'testSynonyms', path: 'x', score: { constant: { value: 1 } } } }");
+
+            AssertRendered(
+                subject.Text("x", "foo", new SearchTextOptions<BsonDocument> {Score = scoreBuilder.Constant(1), MatchCriteria = MatchCriteria.All}),
+                "{ text: { query: 'foo', matchCriteria: 'all', path: 'x', score: { constant: { value: 1 } } } }");
         }
 
         [Fact]
@@ -1105,6 +1129,9 @@ public void Text_typed()
             AssertRendered(
                 subject.Text(x => x.FirstName, "foo"),
                 "{ text: { query: 'foo', path: 'fn' } }");
+            AssertRendered(
+                subject.Text(x => x.FirstName, "foo", new SearchTextOptions<Person> { MatchCriteria = MatchCriteria.All}),
+                "{ text: { query: 'foo', matchCriteria: 'all', path: 'fn' } }");
             AssertRendered(
                 subject.Text("FirstName", "foo"),
                 "{ text: { query: 'foo', path: 'fn' } }");