Added $sample helper to the Aggregates builder

rozza · rozza · commit 002335610915 · 2015-10-06T16:30:52.000+01:00
JAVA-1937
diff --git a/docs/reference/content/builders/aggregation.md b/docs/reference/content/builders/aggregation.md
@@ -57,6 +57,14 @@ This example simply projects the `qty` field into a new field called `quantity`.
 project(computed("quantity", "$qty"))
 ```
 
+### Sample
+The [`$sample`]({{< docsref "reference/operator/aggregation/sample/" >}}) pipeline stage randomly select N documents from its input.
+This example creates a pipeline stage that randomly selects 5 documents from the collection:
+
+```java
+sample(5)
+```
+
 ### Sort
   
 The [`$sort`]({{< docsref "reference/operator/aggregation/sort/" >}}) pipeline stage passes all documents to the next stage, 
diff --git a/driver-core/src/main/com/mongodb/client/model/Aggregates.java b/driver-core/src/main/com/mongodb/client/model/Aggregates.java
@@ -165,6 +165,19 @@ public static Bson out(final String collectionName) {
         return new BsonDocument("$out", new BsonString(collectionName));
     }
 
+    /**
+     * Creates a $sample pipeline stage with the specified sample size
+     *
+     * @param size the sample size
+     * @return the $sample pipeline stage
+     * @mongodb.driver.manual reference/operator/aggregation/sample/  $sample
+     * @mongodb.server.release 3.2
+     * @since 3.2
+     */
+    public static Bson sample(final int size) {
+        return new BsonDocument("$sample", new BsonDocument("size", new BsonInt32(size)));
+    }
+
     private static class SimplePipelineStage implements Bson {
         private final String name;
         private final Bson value;
diff --git a/driver-core/src/test/functional/com/mongodb/client/model/AggregatesFunctionalSpecification.groovy b/driver-core/src/test/functional/com/mongodb/client/model/AggregatesFunctionalSpecification.groovy
@@ -36,6 +36,7 @@ import static com.mongodb.client.model.Aggregates.limit
 import static com.mongodb.client.model.Aggregates.match
 import static com.mongodb.client.model.Aggregates.out
 import static com.mongodb.client.model.Aggregates.project
+import static com.mongodb.client.model.Aggregates.sample
 import static com.mongodb.client.model.Aggregates.skip
 import static com.mongodb.client.model.Aggregates.sort
 import static com.mongodb.client.model.Aggregates.unwind
@@ -46,6 +47,7 @@ import static com.mongodb.client.model.Projections.fields
 import static com.mongodb.client.model.Projections.include
 import static com.mongodb.client.model.Sorts.descending
 import static java.util.Arrays.asList
+import static org.spockframework.util.CollectionUtil.containsAny
 
 class AggregatesFunctionalSpecification extends OperationFunctionalSpecification {
 
@@ -162,4 +164,10 @@ class AggregatesFunctionalSpecification extends OperationFunctionalSpecification
         results.get('stdDevSamp') == 1.0
     }
 
+    @IgnoreIf({ !serverVersionAtLeast(asList(3, 1, 8)) })
+    def '$sample'() {
+        expect:
+        containsAny([a, b, c], aggregate([sample(1)]).first())
+    }
+
 }
diff --git a/driver-core/src/test/unit/com/mongodb/client/model/AggregatesSpecification.groovy b/driver-core/src/test/unit/com/mongodb/client/model/AggregatesSpecification.groovy
@@ -35,6 +35,7 @@ import static com.mongodb.client.model.Accumulators.min
 import static com.mongodb.client.model.Aggregates.out
 import static com.mongodb.client.model.Aggregates.project
 import static com.mongodb.client.model.Accumulators.push
+import static com.mongodb.client.model.Aggregates.sample
 import static com.mongodb.client.model.Aggregates.skip
 import static com.mongodb.client.model.Aggregates.sort
 import static com.mongodb.client.model.Accumulators.sum
@@ -137,6 +138,11 @@ class AggregatesSpecification extends Specification {
         ])) == groupDocument
     }
 
+    def 'should render $sample'() {
+        expect:
+        toBson(sample(5)) == parse('{ $sample : { size: 5} }')
+    }
+
     def toBson(Bson bson) {
         bson.toBsonDocument(BsonDocument, registry)
     }
