CSHARP-4778: Add synonym support to text operator for Atlas Search (#1186)

Author: adelinowona

src/MongoDB.Driver/Search/OperatorSearchDefinitions.cs

@@ -399,23 +399,27 @@ internal sealed class TextSearchDefinition<TDocument> : OperatorSearchDefinition
     {
         private readonly SearchFuzzyOptions _fuzzy;
         private readonly SearchQueryDefinition _query;
+        private readonly string _synonyms;
 
         public TextSearchDefinition(
             SearchPathDefinition<TDocument> path,
             SearchQueryDefinition query,
             SearchFuzzyOptions fuzzy,
-            SearchScoreDefinition<TDocument> score)
+            SearchScoreDefinition<TDocument> score,
+            string synonyms)
                 : base(OperatorType.Text, path, score)
         {
             _query = Ensure.IsNotNull(query, nameof(query));
             _fuzzy = fuzzy;
+            _synonyms = synonyms;
         }
 
         private protected override BsonDocument RenderArguments(SearchDefinitionRenderContext<TDocument> renderContext) =>
             new()
             {
                 { "query", _query.Render() },
                 { "fuzzy", () => _fuzzy.Render(), _fuzzy != null },
+                { "synonyms", _synonyms, _synonyms != null }
             };
     }
 

src/MongoDB.Driver/Search/SearchDefinitionBuilder.cs

@@ -627,7 +627,23 @@ public SearchDefinition<TDocument> Text(
             SearchQueryDefinition query,
             SearchFuzzyOptions fuzzy = null,
             SearchScoreDefinition<TDocument> score = null) =>
-                new TextSearchDefinition<TDocument>(path, query, fuzzy, score);
+                new TextSearchDefinition<TDocument>(path, query, fuzzy, score, null);
+
+        /// <summary>
+        /// Creates a search definition that performs full-text search with synonyms 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="synonyms">The name of the synonym mapping definition in the index definition</param>
+        /// <param name="score">The score modifier.</param>
+        /// <returns>A text search definition.</returns>
+        public SearchDefinition<TDocument> Text(
+            SearchPathDefinition<TDocument> path,
+            SearchQueryDefinition query,
+            string synonyms,
+            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
@@ -646,6 +662,23 @@ public SearchDefinition<TDocument> Text<TField>(
             SearchScoreDefinition<TDocument> score = null) =>
                 Text(new ExpressionFieldDefinition<TDocument>(path), query, fuzzy, score);
 
+        /// <summary>
+        /// Creates a search definition that performs full-text search with synonyms 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="synonyms">The name of the synonym mapping definition in the index definition</param>
+        /// <param name="score">The score modifier.</param>
+        /// <returns>A text search definition.</returns>
+        public SearchDefinition<TDocument> Text<TField>(
+            Expression<Func<TDocument, TField>> path,
+            SearchQueryDefinition query,
+            string synonyms,
+            SearchScoreDefinition<TDocument> score = null) =>
+                Text(new ExpressionFieldDefinition<TDocument>(path), query, synonyms, score);
+
         /// <summary>
         /// Creates a search definition that uses special characters in the search string that can
         /// match any character.

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

@@ -477,6 +477,51 @@ public void Text()
             result.Title.Should().Be("Declaration of Independence");
         }
 
+        [Theory]
+        [InlineData("automobile", "transportSynonyms", "Blue Car")]
+        [InlineData("boat", "transportSynonyms", "And the Ship Sails On")]
+        public void TextWithSynonymsReturnsCorrectResult(string query, string synonym, string expected)
+        {
+            var sortDefinition = Builders<Movie>.Sort.Ascending(x => x.Title);
+            var result =
+                GetSynonymTestCollection().Aggregate()
+                    .Search(Builders<Movie>.Search.Text(x => x.Title, query, synonym), indexName: "synonyms-tests")
+                    .Sort(sortDefinition)
+                    .Project<Movie>(Builders<Movie>.Projection.Include("Title").Exclude("_id"))
+                    .Limit(1)
+                    .Single();
+
+            result.Title.Should().Be(expected);
+        }
+
+        [Fact]
+        public void TextWithSynonymsMappings()
+        {
+            var automobileAndAttireSearchResults = SearchMultipleSynonymMapping(
+                Builders<Movie>.Search.Text(x => x.Title, "automobile", "transportSynonyms"),
+                Builders<Movie>.Search.Text(x => x.Title, "attire", "attireSynonyms"));
+
+            var vehicleAndDressSearchResults = SearchMultipleSynonymMapping(
+                Builders<Movie>.Search.Text(x => x.Title, "vehicle", "transportSynonyms"),
+                Builders<Movie>.Search.Text(x => x.Title, "dress", "attireSynonyms"));
+
+            var boatAndHatSearchResults = SearchMultipleSynonymMapping(
+                Builders<Movie>.Search.Text(x => x.Title, "boat", "transportSynonyms"),
+                Builders<Movie>.Search.Text(x => x.Title, "hat", "attireSynonyms"));
+
+            var vesselAndFedoraSearchResults = SearchMultipleSynonymMapping(
+                Builders<Movie>.Search.Text(x => x.Title, "vessel", "transportSynonyms"),
+                Builders<Movie>.Search.Text(x => x.Title, "fedora", "attireSynonyms"));
+
+            automobileAndAttireSearchResults.Should().NotBeNull();
+            vehicleAndDressSearchResults.Should().NotBeNull();
+            boatAndHatSearchResults.Should().NotBeNull();
+            vesselAndFedoraSearchResults.Should().NotBeNull();
+
+            automobileAndAttireSearchResults.Should().BeEquivalentTo(vehicleAndDressSearchResults);
+            boatAndHatSearchResults.Should().NotBeEquivalentTo(vesselAndFedoraSearchResults);
+        }
+
         [Fact]
         public void Wildcard()
         {
@@ -500,9 +545,15 @@ private HistoricalDocument SearchSingle(
                 fluent = fluent.Project(projectionDefinition);
             }
 
-            return fluent.Limit(1).ToList().Single();
+            return fluent.Limit(1).Single();
         }
 
+        private List<BsonDocument> SearchMultipleSynonymMapping(params SearchDefinition<Movie>[] clauses) =>
+            GetSynonymTestCollection().Aggregate()
+                .Search(Builders<Movie>.Search.Compound().Should(clauses), indexName: "synonyms-tests")
+                .Project(Builders<Movie>.Projection.Include("Title").Exclude("_id"))
+                .ToList();
+
         private IMongoCollection<HistoricalDocument> GetTestCollection() => _disposableMongoClient
             .GetDatabase("sample_training")
             .GetCollection<HistoricalDocument>("posts");
@@ -511,6 +562,10 @@ private IMongoCollection<T> GetTestCollection<T>() => _disposableMongoClient
             .GetDatabase("sample_training")
             .GetCollection<T>("posts");
 
+        private IMongoCollection<Movie> GetSynonymTestCollection() => _disposableMongoClient
+            .GetDatabase("sample_mflix")
+            .GetCollection<Movie>("movies");
+
         private IMongoCollection<AirbnbListing> GetGeoTestCollection() => _disposableMongoClient
             .GetDatabase("sample_airbnb")
             .GetCollection<AirbnbListing>("listingsAndReviews");
@@ -522,6 +577,13 @@ public class Comment
             public string Author { get; set; }
         }
 
+        [BsonIgnoreExtraElements]
+        public class Movie
+        {
+            [BsonElement("title")]
+            public string Title { get; set; }
+        }
+
         [BsonIgnoreExtraElements]
         public class HistoricalDocumentWithCommentsOnly
         {

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

@@ -939,6 +939,10 @@ public void Text()
                 subject.Text(new[] { "x", "y" }, new[] { "foo", "bar" }),
                 "{ text: { query: ['foo', 'bar'], path: ['x', 'y'] } }");
 
+            AssertRendered(
+                subject.Text(new[] { "x", "y" }, new[] { "foo", "bar" }, "testSynonyms"),
+                "{ text: { query: ['foo', 'bar'], synonyms: 'testSynonyms', path: ['x', 'y'] } }");
+
             AssertRendered(
                 subject.Text("x", "foo", new SearchFuzzyOptions()),
                 "{ text: { query: 'foo', path: 'x', fuzzy: {} } }");
@@ -955,6 +959,9 @@ public void Text()
             AssertRendered(
                 subject.Text("x", "foo", score: scoreBuilder.Constant(1)),
                 "{ text: { query: 'foo', path: 'x', score: { constant: { value: 1 } } } }");
+            AssertRendered(
+                subject.Text("x", "foo", "testSynonyms", scoreBuilder.Constant(1)),
+                "{ text: { query: 'foo', synonyms: 'testSynonyms', path: 'x', score: { constant: { value: 1 } } } }");
         }
 
         [Fact]
@@ -985,6 +992,9 @@ public void Text_typed()
             AssertRendered(
                 subject.Text(x => x.FirstName, new[] { "foo", "bar" }),
                 "{ text: { query: ['foo', 'bar'], path: 'fn' } }");
+            AssertRendered(
+                subject.Text(x => x.FirstName, new[] { "foo", "bar" }, "testSynonyms"),
+                "{ text: { query: ['foo', 'bar'], synonyms: 'testSynonyms', path: 'fn' } }");
             AssertRendered(
                 subject.Text("FirstName", new[] { "foo", "bar" }),
                 "{ text: { query: ['foo', 'bar'], path: 'fn' } }");