CSHARP-4732: Add SearchOptions overload to Search API (#1149)

Author: BorisDog

src/MongoDB.Driver/AggregateFluent.cs

@@ -244,11 +244,26 @@ public override IAggregateFluent<TResult> Search(
             SearchHighlightOptions<TResult> highlight = null,
             string indexName = null,
             SearchCountOptions count = null,
-            SortDefinition<TResult> sort = null,
             bool returnStoredSource = false,
             bool scoreDetails = false)
         {
-            return WithPipeline(_pipeline.Search(searchDefinition, highlight, indexName, count, sort, returnStoredSource, scoreDetails));
+            var searchOptions = new SearchOptions<TResult>()
+            {
+                CountOptions = count,
+                Highlight = highlight,
+                IndexName = indexName,
+                ReturnStoredSource = returnStoredSource,
+                ScoreDetails = scoreDetails
+            };
+
+            return WithPipeline(_pipeline.Search(searchDefinition, searchOptions));
+        }
+
+        public override IAggregateFluent<TResult> Search(
+            SearchDefinition<TResult> searchDefinition,
+            SearchOptions<TResult> searchOptions)
+        {
+            return WithPipeline(_pipeline.Search(searchDefinition, searchOptions));
         }
 
         public override IAggregateFluent<SearchMetaResult> SearchMeta(

src/MongoDB.Driver/AggregateFluentBase.cs

@@ -222,13 +222,20 @@ public virtual IAggregateFluent<TResult> Search(
             SearchHighlightOptions<TResult> highlight = null,
             string indexName = null,
             SearchCountOptions count = null,
-            SortDefinition<TResult> sort = null,
             bool returnStoredSource = false,
             bool scoreDetails = false)
         {
             throw new NotImplementedException();
         }
 
+        /// <inheritdoc />
+        public virtual IAggregateFluent<TResult> Search(
+            SearchDefinition<TResult> searchDefinition,
+            SearchOptions<TResult> searchOptions)
+        {
+            throw new NotImplementedException();
+        }
+
         /// <inheritdoc />
         public virtual IAggregateFluent<SearchMetaResult> SearchMeta(
             SearchDefinition<TResult> searchDefinition,

src/MongoDB.Driver/IAggregateFluent.cs

@@ -361,25 +361,35 @@ IAggregateFluent<BsonDocument> SetWindowFields<TWindowFields>(
         /// <param name="highlight">The highlight options.</param>
         /// <param name="indexName">The index name.</param>
         /// <param name="count">The count options.</param>
-        /// <param name="sort">The sort specification.</param>
         /// <param name="returnStoredSource">
         /// Flag that specifies whether to perform a full document lookup on the backend database
         /// or return only stored source fields directly from Atlas Search.
         /// </param>
         /// <param name="scoreDetails">
         /// Flag that specifies whether to return a detailed breakdown
-        /// of the score for each document in the result. 
+        /// of the score for each document in the result.
         /// </param>
         /// <returns>The fluent aggregate interface.</returns>
         IAggregateFluent<TResult> Search(
             SearchDefinition<TResult> searchDefinition,
             SearchHighlightOptions<TResult> highlight = null,
             string indexName = null,
             SearchCountOptions count = null,
-            SortDefinition<TResult> sort = null,
             bool returnStoredSource = false,
             bool scoreDetails = false);
 
+        /// <summary>
+        /// Appends a $search stage to the pipeline.
+        /// </summary>
+        /// <param name="searchDefinition">The search definition.</param>
+        /// <param name="searchOptions">The search options.</param>
+        /// <returns>
+        /// The fluent aggregate interface.
+        /// </returns>
+        IAggregateFluent<TResult> Search(
+            SearchDefinition<TResult> searchDefinition,
+            SearchOptions<TResult> searchOptions);
+
         /// <summary>
         /// Appends a $searchMeta stage to the pipeline.
         /// </summary>

src/MongoDB.Driver/Linq/MongoQueryable.cs

@@ -1145,7 +1145,6 @@ public static IMongoQueryable<TSource> Sample<TSource>(this IMongoQueryable<TSou
         /// <param name="highlight">The highlight options.</param>
         /// <param name="indexName">The index name.</param>
         /// <param name="count">The count options.</param>
-        /// <param name="sort">The sort specification.</param>
         /// <param name="returnStoredSource">
         /// Flag that specifies whether to perform a full document lookup on the backend database
         /// or return only stored source fields directly from Atlas Search.
@@ -1161,13 +1160,37 @@ public static IMongoQueryable<TSource> Search<TSource>(
             SearchHighlightOptions<TSource> highlight = null,
             string indexName = null,
             SearchCountOptions count = null,
-            SortDefinition<TSource> sort = null,
             bool returnStoredSource = false,
             bool scoreDetails = false)
+        {
+            var searchOptions = new SearchOptions<TSource>()
+            {
+                CountOptions = count,
+                Highlight = highlight,
+                IndexName = indexName,
+                ReturnStoredSource = returnStoredSource,
+                ScoreDetails = scoreDetails
+            };
+
+            return Search(source, searchDefinition, searchOptions);
+        }
+
+        /// <summary>
+        /// Appends a $search stage to the LINQ pipeline.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
+        /// <param name="source">A sequence of values.</param>
+        /// <param name="searchDefinition">The search definition.</param>
+        /// <param name="searchOptions">The search options.</param>
+        /// <returns>The queryable with a new stage appended.</returns>
+        public static IMongoQueryable<TSource> Search<TSource>(
+            this IMongoQueryable<TSource> source,
+            SearchDefinition<TSource> searchDefinition,
+            SearchOptions<TSource> searchOptions)
         {
             return AppendStage(
                 source,
-                PipelineStageDefinitionBuilder.Search(searchDefinition, highlight, indexName, count, sort, returnStoredSource, scoreDetails));
+                PipelineStageDefinitionBuilder.Search(searchDefinition, searchOptions));
         }
 
         /// <summary>

src/MongoDB.Driver/PipelineDefinitionBuilder.cs

@@ -1175,7 +1175,6 @@ public static PipelineDefinition<TInput, TOutput> ReplaceWith<TInput, TIntermedi
         /// <param name="highlight">The highlight options.</param>
         /// <param name="indexName">The index name.</param>
         /// <param name="count">The count options.</param>
-        /// <param name="sort">The sort specification.</param>
         /// <param name="returnStoredSource">
         /// Flag that specifies whether to perform a full document lookup on the backend database
         /// or return only stored source fields directly from Atlas Search.
@@ -1193,12 +1192,31 @@ public static PipelineDefinition<TInput, TOutput> Search<TInput, TOutput>(
             SearchHighlightOptions<TOutput> highlight = null,
             string indexName = null,
             SearchCountOptions count = null,
-            SortDefinition<TOutput> sort = null,
             bool returnStoredSource = false,
             bool scoreDetails = false)
         {
             Ensure.IsNotNull(pipeline, nameof(pipeline));
-            return pipeline.AppendStage(PipelineStageDefinitionBuilder.Search(searchDefinition, highlight, indexName, count, sort, returnStoredSource, scoreDetails));
+            return pipeline.AppendStage(PipelineStageDefinitionBuilder.Search(searchDefinition, highlight, indexName, count, returnStoredSource, scoreDetails));
+        }
+
+        /// <summary>
+        /// Appends a $search stage to the pipeline.
+        /// </summary>
+        /// <typeparam name="TInput">The type of the input documents.</typeparam>
+        /// <typeparam name="TOutput">The type of the output documents.</typeparam>
+        /// <param name="pipeline">The pipeline.</param>
+        /// <param name="searchDefinition">The search definition.</param>
+        /// <param name="searchOptions">The search options.</param>
+        /// <returns>
+        /// A new pipeline with an additional stage.
+        /// </returns>
+        public static PipelineDefinition<TInput, TOutput> Search<TInput, TOutput>(
+            this PipelineDefinition<TInput, TOutput> pipeline,
+            SearchDefinition<TOutput> searchDefinition,
+            SearchOptions<TOutput> searchOptions)
+        {
+            Ensure.IsNotNull(pipeline, nameof(pipeline));
+            return pipeline.AppendStage(PipelineStageDefinitionBuilder.Search(searchDefinition, searchOptions));
         }
 
         /// <summary>

src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs

@@ -1316,7 +1316,6 @@ public static PipelineStageDefinition<TInput, TOutput> Project<TInput, TOutput>(
         /// <param name="highlight">The highlight options.</param>
         /// <param name="indexName">The index name.</param>
         /// <param name="count">The count options.</param>
-        /// <param name="sort">The sort specification.</param>
         /// <param name="returnStoredSource">
         /// Flag that specifies whether to perform a full document lookup on the backend database
         /// or return only stored source fields directly from Atlas Search.
@@ -1331,9 +1330,31 @@ public static PipelineStageDefinition<TInput, TInput> Search<TInput>(
             SearchHighlightOptions<TInput> highlight = null,
             string indexName = null,
             SearchCountOptions count = null,
-            SortDefinition<TInput> sort = null,
             bool returnStoredSource = false,
             bool scoreDetails = false)
+        {
+            var searchOptions = new SearchOptions<TInput>()
+            {
+                CountOptions = count,
+                Highlight = highlight,
+                IndexName = indexName,
+                ReturnStoredSource = returnStoredSource,
+                ScoreDetails = scoreDetails
+            };
+
+            return Search(searchDefinition, searchOptions);
+        }
+
+        /// <summary>
+        /// Creates a $search stage.
+        /// </summary>
+        /// <typeparam name="TInput">The type of the input documents.</typeparam>
+        /// <param name="searchDefinition">The search definition.</param>
+        /// <param name="searchOptions">The search options.</param>
+        /// <returns>The stage.</returns>
+        public static PipelineStageDefinition<TInput, TInput> Search<TInput>(
+            SearchDefinition<TInput> searchDefinition,
+            SearchOptions<TInput> searchOptions)
         {
             Ensure.IsNotNull(searchDefinition, nameof(searchDefinition));
 
@@ -1343,12 +1364,12 @@ public static PipelineStageDefinition<TInput, TInput> Search<TInput>(
                 (s, sr, linqProvider) =>
                 {
                     var renderedSearchDefinition = searchDefinition.Render(s, sr);
-                    renderedSearchDefinition.Add("highlight", () => highlight.Render(s, sr), highlight != null);
-                    renderedSearchDefinition.Add("count", () => count.Render(), count != null);
-                    renderedSearchDefinition.Add("sort", () => sort.Render(s, sr), sort != null);
-                    renderedSearchDefinition.Add("index", indexName, indexName != null);
-                    renderedSearchDefinition.Add("returnStoredSource", returnStoredSource, returnStoredSource);
-                    renderedSearchDefinition.Add("scoreDetails", scoreDetails, scoreDetails);
+                    renderedSearchDefinition.Add("highlight", () => searchOptions.Highlight.Render(s, sr), searchOptions.Highlight != null);
+                    renderedSearchDefinition.Add("count", () => searchOptions.CountOptions.Render(), searchOptions.CountOptions != null);
+                    renderedSearchDefinition.Add("sort", () => searchOptions.Sort.Render(s, sr), searchOptions.Sort != null);
+                    renderedSearchDefinition.Add("index", searchOptions.IndexName, searchOptions.IndexName != null);
+                    renderedSearchDefinition.Add("returnStoredSource", searchOptions.ReturnStoredSource, searchOptions.ReturnStoredSource);
+                    renderedSearchDefinition.Add("scoreDetails", searchOptions.ScoreDetails, searchOptions.ScoreDetails);
 
                     var document = new BsonDocument(operatorName, renderedSearchDefinition);
                     return new RenderedPipelineStageDefinition<TInput>(operatorName, document, s);

src/MongoDB.Driver/Search/SearchOptions.cs

@@ -0,0 +1,55 @@
+/* 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 search.
+    /// </summary>
+    public sealed class SearchOptions<TResult>
+    {
+        /// <summary>
+        /// Gets or sets the options for counting the search results.
+        /// </summary>
+        public SearchCountOptions CountOptions { get; set; }
+
+        /// <summary>
+        /// Gets or sets the options for highlighting.
+        /// </summary>
+        public SearchHighlightOptions<TResult> Highlight { get; set; }
+
+        /// <summary>
+        /// Gets or sets the index name.
+        /// </summary>
+        public string IndexName { get; set; }
+
+        /// <summary>
+        /// Gets or sets a flag that specifies whether to perform a full document lookup on the backend database
+        /// or return only stored source fields directly from Atlas Search.
+        /// </summary>
+        public bool ReturnStoredSource { get; set; }
+
+        /// <summary>
+        /// Gets or sets a flag that specifies whether to return a detailed breakdown
+        /// of the score for each document in the result.
+        /// </summary>
+        public bool ScoreDetails { get; set; }
+
+        /// <summary>
+        /// Gets or sets the sort specification.
+        /// </summary>
+        public SortDefinition<TResult> Sort { get; set; }
+    }
+}

tests/MongoDB.Driver.Tests/PipelineDefinitionBuilderTests.cs

@@ -201,7 +201,7 @@ public void Search_should_add_expected_stage_with_sort()
             var builder = new SearchDefinitionBuilder<BsonDocument>();
             var sortBuilder = new SortDefinitionBuilder<BsonDocument>();
 
-            var result = pipeline.Search(builder.Text("bar", "foo"), sort: sortBuilder.Ascending("foo"));
+            var result = pipeline.Search(builder.Text("bar", "foo"), new() { Sort = sortBuilder.Ascending("foo") });
 
             var stages = RenderStages(result, BsonDocumentSerializer.Instance);
             stages[0].Should().Be("{ $search: { text: { query: 'foo', path: 'bar' }, sort: { 'foo': 1 } } }");

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

@@ -420,7 +420,7 @@ public void Sort()
             var results = GetTestCollection().Aggregate()
                 .Search(
                     Builders.Search.Text(x => x.Body, "liberty"),
-                    sort: Builders.Sort.Descending(x => x.Title))
+                    new() { Sort = Builders.Sort.Descending(x => x.Title) })
                 .Project<HistoricalDocument>(Builders.Projection.Include(x => x.Title))
                 .Limit(1)
                 .ToList();
@@ -473,7 +473,7 @@ private HistoricalDocument SearchSingle(
             ProjectionDefinition<HistoricalDocument, HistoricalDocument> projectionDefinition = null,
             SortDefinition<HistoricalDocument> sort = null)
         {
-            var fluent = GetTestCollection().Aggregate().Search(searchDefintion, sort: sort);
+            var fluent = GetTestCollection().Aggregate().Search(searchDefintion, new() { Sort = sort });
 
             if (projectionDefinition != null)
             {