CSHARP-2659 - Adding support for $sample aggregation pipeline stage.

src/MongoDB.Driver/AggregateFluent.cs

@@ -235,6 +235,11 @@ public override IAggregateFluent<AggregateSortByCountResult<TId>> SortByCount<TI
             return WithPipeline(_pipeline.SortByCount(id));
         }
 
+        public override IAggregateFluent<TResult> Sample(int size)
+        {
+            return WithPipeline(_pipeline.Sample(size));
+        }
+
         public override IOrderedAggregateFluent<TResult> ThenBy(SortDefinition<TResult> newSort)
         {
             Ensure.IsNotNull(newSort, nameof(newSort));

src/MongoDB.Driver/AggregateFluentBase.cs

@@ -203,6 +203,9 @@ public virtual IAggregateFluent<TNewResult> ReplaceWith<TNewResult>(AggregateExp
         /// <inheritdoc />
         public abstract IAggregateFluent<TResult> Sort(SortDefinition<TResult> sort);
 
+        /// <inheritdoc />
+        public abstract IAggregateFluent<TResult> Sample(int size);
+
         /// <inheritdoc />
         public virtual IAggregateFluent<AggregateSortByCountResult<TId>> SortByCount<TId>(AggregateExpressionDefinition<TResult, TId> id)
         {

src/MongoDB.Driver/IAggregateFluent.cs

@@ -386,6 +386,13 @@ public interface IAggregateFluent<TResult> : IAsyncCursorSource<TResult>
         /// <param name="options">The options.</param>
         /// <returns>The fluent aggregate interface.</returns>
         IAggregateFluent<TNewResult> Unwind<TNewResult>(FieldDefinition<TResult> field, AggregateUnwindOptions<TNewResult> options = null);
+
+        /// <summary>
+        /// Appends a sample stage to the pipeline.
+        /// </summary>
+        /// <param name="size">The sample size.</param>
+        /// <returns>The fluent aggregate interface.</returns>
+        IAggregateFluent<TResult> Sample(int size);
     }
 
     /// <summary>

src/MongoDB.Driver/PipelineDefinitionBuilder.cs

@@ -1044,6 +1044,25 @@ public static class PipelineDefinitionBuilder
             return pipeline.AppendStage(PipelineStageDefinitionBuilder.Sort(sort));
         }
 
+
+        /// <summary>
+        /// Appends a $sample 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="size">The sample size.</param>
+        /// <returns>
+        /// A new pipeline with an additional stage.
+        /// </returns>
+        public static PipelineDefinition<TInput, TOutput> Sample<TInput, TOutput>(
+            this PipelineDefinition<TInput, TOutput> pipeline,
+            int size)
+        {
+            Ensure.IsNotNull(pipeline, nameof(pipeline));
+            return pipeline.AppendStage(PipelineStageDefinitionBuilder.Sample<TOutput>(size));
+        }
+
         /// <summary>
         /// Appends a $sortByCount stage to the pipeline.
         /// </summary>

src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs

@@ -1249,6 +1249,19 @@ public static class PipelineStageDefinitionBuilder
             return new SortPipelineStageDefinition<TInput>(sort);
         }
 
+        /// <summary>
+        /// Creates a $sample stage.
+        /// </summary>
+        /// <typeparam name="TInput">The type of the input documents.</typeparam>
+        /// <param name="size">The size.</param>
+        /// <returns>The stage.</returns>
+        public static PipelineStageDefinition<TInput, TInput> Sample<TInput>(
+            int size)
+        {
+            Ensure.IsGreaterThanOrEqualToZero(size, nameof(size));
+            return new BsonDocumentPipelineStageDefinition<TInput, TInput>(new BsonDocument("$sample", new BsonDocument("size", size)));
+        }
+
         /// <summary>
         /// Creates a $sortByCount stage.
         /// </summary>

tests/MongoDB.Driver.Tests/PipelineDefinitionBuilderTests.cs

@@ -114,6 +114,18 @@ public void Merge_should_add_expected_stage()
             stages[0].Should().Be("{ $merge : { into : { db : 'database', coll : 'collection' } } }");
         }
 
+        [Fact]
+        public void Sample_should_add_expected_stage()
+        {
+            var pipeline = new EmptyPipelineDefinition<BsonDocument>();
+
+            var result = pipeline.Sample(15);
+
+            var stages = RenderStages(result, BsonDocumentSerializer.Instance);
+            stages.Count.Should().Be(1);
+            stages[0].Should().Be("{ $sample: { size: 15 } }");
+        }
+
         [Fact]
         public void UnionWith_should_add_expected_stage()
         {