CSHARP-5420: Driver Support for Search Sequential Pagination (#1558)

Author: papafe

src/MongoDB.Driver/IAggregateFluent.cs

@@ -404,6 +404,7 @@ IAggregateFluent<TNewResult> Lookup<TForeignDocument, TAsElement, TAs, TNewResul
         IAggregateFluent<BsonDocument> SetWindowFields<TWindowFields>(
             AggregateExpressionDefinition<ISetWindowFieldsPartition<TResult>, TWindowFields> output);
 
+        //TODO If I add a parameter here, then this would be a binary breaking change
         /// <summary>
         /// Appends a $search stage to the pipeline.
         /// </summary>

src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs

@@ -1386,6 +1386,8 @@ public static PipelineStageDefinition<TInput, TInput> Search<TInput>(
                     renderedSearchDefinition.Add("returnStoredSource", searchOptions.ReturnStoredSource, searchOptions.ReturnStoredSource);
                     renderedSearchDefinition.Add("scoreDetails", searchOptions.ScoreDetails, searchOptions.ScoreDetails);
                     renderedSearchDefinition.Add("tracking", () => searchOptions.Tracking.Render(), searchOptions.Tracking != null);
+                    renderedSearchDefinition.Add("searchAfter", () => searchOptions.SearchAfter, searchOptions.SearchAfter != null);
+                    renderedSearchDefinition.Add("searchBefore", () => searchOptions.SearchBefore, searchOptions.SearchBefore != null);
 
                     var document = new BsonDocument(operatorName, renderedSearchDefinition);
                     return new RenderedPipelineStageDefinition<TInput>(operatorName, document, args.DocumentSerializer);

src/MongoDB.Driver/ProjectionDefinitionBuilder.cs

@@ -257,6 +257,40 @@ public static ProjectionDefinition<TDocument> MetaSearchScoreDetails<TDocument>(
             return builder.Combine(projection, builder.MetaSearchScoreDetails(field));
         }
 
+        /// <summary>
+        /// Combines an existing projection with a search sequence token projection.
+        /// </summary>
+        /// <typeparam name="TDocument">The type of the document.</typeparam>
+        /// <param name="projection">The projection.</param>
+        /// <param name="field">The field.</param>
+        /// <returns>
+        /// A combined projection.
+        /// </returns>
+        public static ProjectionDefinition<TDocument> MetaSearchSequenceToken<TDocument>(
+            this ProjectionDefinition<TDocument> projection,
+            FieldDefinition<TDocument> field)
+        {
+            var builder = Builders<TDocument>.Projection;
+            return builder.Combine(projection, builder.MetaSearchSequenceToken(field));
+        }
+
+        /// <summary>
+        /// Combines an existing projection with a search sequence token projection.
+        /// </summary>
+        /// <typeparam name="TDocument">The type of the document.</typeparam>
+        /// <param name="projection">The projection.</param>
+        /// <param name="field">The field.</param>
+        /// <returns>
+        /// A combined projection.
+        /// </returns>
+        public static ProjectionDefinition<TDocument> MetaSearchSequenceToken<TDocument>(
+            this ProjectionDefinition<TDocument> projection,
+            Expression<Func<TDocument, object>> field)
+        {
+            var builder = Builders<TDocument>.Projection;
+            return builder.Combine(projection, builder.MetaSearchSequenceToken(field));
+        }
+
         /// <summary>
         /// Combines an existing projection with a text score projection.
         /// </summary>
@@ -576,7 +610,7 @@ public ProjectionDefinition<TSource> Include(Expression<Func<TSource, object>> f
         /// <param name="field">The field.</param>
         /// <param name="metaFieldName">The meta field name.</param>
         /// <returns>
-        /// A text score projection.
+        /// A meta projection.
         /// </returns>
         public ProjectionDefinition<TSource> Meta(FieldDefinition<TSource> field, string metaFieldName)
         {
@@ -655,6 +689,30 @@ public ProjectionDefinition<TSource> MetaSearchScoreDetails<TField>(Expression<F
             return MetaSearchScoreDetails(new ExpressionFieldDefinition<TSource>(field));
         }
 
+        /// <summary>
+        /// Creates a search sequence token projection.
+        /// </summary>
+        /// <param name="field">The field.</param>
+        /// <returns>
+        /// A search sequence token projection.
+        /// </returns>
+        public ProjectionDefinition<TSource> MetaSearchSequenceToken(FieldDefinition<TSource> field)
+        {
+            return Meta(field, "searchSequenceToken");
+        }
+
+        /// <summary>
+        /// Creates a search sequence token projection.
+        /// </summary>
+        /// <param name="field">The field.</param>
+        /// <returns>
+        /// A search sequence token projection.
+        /// </returns>
+        public ProjectionDefinition<TSource> MetaSearchSequenceToken<TField>(Expression<Func<TSource, TField>> field)
+        {
+            return MetaSearchSequenceToken(new ExpressionFieldDefinition<TSource>(field));
+        }
+
         /// <summary>
         /// Creates a text score projection.
         /// </summary>

src/MongoDB.Driver/Search/SearchOptions.cs

@@ -57,5 +57,17 @@ public sealed class SearchOptions<TDocument>
         /// Gets or sets the options for tracking search terms.
         /// </summary>
         public SearchTrackingOptions Tracking { get; set; }
+
+        /// <summary>
+        /// Gets or sets the "after" reference point for pagination.
+        /// When set, the search retrieves documents starting immediately after the specified reference point.
+        /// </summary>
+        public string SearchAfter { get; set; }
+
+        /// <summary>
+        /// Gets or sets the "before" reference point for pagination.
+        /// When set, the search retrieves documents starting immediately before the specified reference point.
+        /// </summary>
+        public string SearchBefore { get; set; }
     }
 }

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

@@ -288,7 +288,6 @@ public void Phrase()
         {
             // This test case exercises the indexName and returnStoredSource arguments. The
             // remaining test cases omit them.
-            var coll = GetTestCollection();
             var results = GetTestCollection().Aggregate()
                 .Search(Builders.Search.Phrase(x => x.Body, "life, liberty, and the pursuit of happiness"),
                     new SearchHighlightOptions<HistoricalDocument>(x => x.Body),
@@ -381,6 +380,78 @@ public void Range()
             results.Should().ContainSingle().Which.Name.Should().Be("House close to station & direct to opera house....");
         }
 
+        [Fact]
+        public void SearchSequenceToken()
+        {
+            const int limitVal = 10;
+            var titles = new[]
+            {
+                "Equinox Flower",
+                "Flower Drum Song",
+                "Cactus Flower",
+                "The Flower of My Secret",
+            };
+
+            var searchDefinition = Builders<Movie>.Search.Text(t => t.Title, "flower");
+            var searchOptions = new SearchOptions<Movie>
+            {
+                IndexName = "default",
+                Sort = Builders<Movie>.Sort.Ascending("year")
+            };
+            var projection = Builders<Movie>.Projection
+                .Include(x => x.Title)
+                .MetaSearchSequenceToken(x => x.PaginationToken);
+
+            // Base search
+            var baseSearchResults = GetSynonymTestCollection()
+                .Aggregate()
+                .Search(searchDefinition, searchOptions)
+                .Project<Movie>(projection)
+                .Limit(limitVal)
+                .ToList();
+
+            baseSearchResults.Count.Should().Be(limitVal);
+            baseSearchResults.ForEach( m => m.PaginationToken.Should().NotBeNullOrEmpty());
+            baseSearchResults[0].Title.Should().Be(titles[0]);
+            baseSearchResults[1].Title.Should().Be(titles[1]);
+            baseSearchResults[2].Title.Should().Be(titles[2]);
+            baseSearchResults[3].Title.Should().Be(titles[3]);
+
+            // Testing SearchAfter
+            // We're searching after the 2nd result of the base search
+            searchOptions.SearchAfter = baseSearchResults[1].PaginationToken;
+            var searchAfterResults = GetSynonymTestCollection()
+                .Aggregate()
+                .Search(searchDefinition, searchOptions)
+                .Project<Movie>(projection)
+                .Limit(limitVal)
+                .ToList();
+
+            searchAfterResults.Count.Should().Be(limitVal);
+            searchAfterResults.ForEach( m => m.PaginationToken.Should().NotBeNullOrEmpty());
+            searchAfterResults[0].Title.Should().Be(titles[2]);
+            searchAfterResults[1].Title.Should().Be(titles[3]);
+
+            // Testing SearchBefore
+            // We're searching before the 4th result of the base search
+            searchOptions.SearchAfter = null;
+            searchOptions.SearchBefore = baseSearchResults[3].PaginationToken;
+            var searchBeforeResults = GetSynonymTestCollection()
+                .Aggregate()
+                .Search(searchDefinition, searchOptions)
+                .Project<Movie>(projection)
+                .Limit(limitVal)
+                .ToList();
+
+            // We only get the first 3 elements of the base search
+            searchBeforeResults.Count.Should().Be(3);
+            searchBeforeResults.ForEach( m => m.PaginationToken.Should().NotBeNullOrEmpty());
+            // With searchBefore the results are reversed
+            searchBeforeResults[0].Title.Should().Be(titles[2]);
+            searchBeforeResults[1].Title.Should().Be(titles[1]);
+            searchBeforeResults[2].Title.Should().Be(titles[0]);
+        }
+
         [Fact]
         public void Search_count_lowerBound()
         {
@@ -686,6 +757,9 @@ public class Movie
 
             [BsonElement("score")]
             public double Score { get; set; }
+
+            [BsonElement("paginationToken")]
+            public string PaginationToken { get; set; }
         }
 
         [BsonIgnoreExtraElements]

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

@@ -53,6 +53,16 @@ public void MetaSearchScoreDetails()
             AssertRendered(subjectTyped.MetaSearchScoreDetails(p => p.MetaField), "{ mf : { $meta: 'searchScoreDetails' } }");
         }
 
+        [Fact]
+        public void MetaSearchSequenceToken()
+        {
+            var subject = CreateSubject<BsonDocument>();
+            AssertRendered(subject.MetaSearchSequenceToken("a"), "{ a : { $meta: 'searchSequenceToken' } }");
+
+            var subjectTyped = CreateSubject<SimplestPerson>();
+            AssertRendered(subjectTyped.MetaSearchSequenceToken(p => p.MetaField), "{ mf : { $meta: 'searchSequenceToken' } }");
+        }
+
         [Fact]
         public void MetaVectorSearchScore()
         {