DOCSP-23138: Densify Aggregates Builder (#272)

* DOCSP-23138: Densify Aggregates Builder

Author: Chris Cho

source/fundamentals/builders/aggregates.txt

@@ -787,6 +787,61 @@ and ``temperature`` fields:
    :language: java
    :dedent:
 
+Densify
+-------
+
+Use the ``densify()`` method to create a
+`$densify <https://www.mongodb.com/docs/rapid/reference/operator/aggregation/densify/>`__
+pipeline stage that generates a sequence of documents to span a specified
+interval.
+
+.. tip::
+
+   You can use the ``$densify()`` aggregation stage only when running
+   MongoDB v5.1 or later.
+
+Consider the following documents retrieved from the :atlas:`Atlas sample weather dataset </sample-data/sample-weather>`
+that contain measurements for a similar ``position`` field, spaced one hour
+apart:
+
+.. code-block:: none
+   :copyable: false
+
+   Document{{ _id=5553a..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:00:00 EST 1984, ... }}
+   Document{{ _id=5553b..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 09:00:00 EST 1984, ... }}
+
+Suppose you needed to create a pipeline stage that performs the following
+actions on these documents:
+
+- Add a document at every 15-minute interval for which a ``ts`` value does not
+  already exist.
+- Group the documents by the ``position`` field.
+
+The call to the ``densify()`` aggregation stage builder that accomplishes
+these actions should resemble the following:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateDensify.java
+   :start-after: // begin densify aggregate
+   :end-before: // end densify aggregate
+   :language: java
+   :dedent:
+
+The following output highlights the documents output by the aggregate stage
+which contain ``ts`` values every 15 minutes between the existing documents:
+
+.. code-block:: none
+   :emphasize-lines: 2-4
+   :copyable: false
+
+   Document{{ _id=5553a..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:00:00 EST 1984, ... }}
+   Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:15:00 EST 1984 }}
+   Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:30:00 EST 1984 }}
+   Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:45:00 EST 1984 }}
+   Document{{ _id=5553b..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 09:00:00 EST 1984, ... }}
+
+See the `densify() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#densify(java.lang.String,com.mongodb.client.model.densify.DensifyRange)>`__
+for more information.
+
 Atlas Full-Text Search
 ----------------------
 

source/includes/fundamentals/code-snippets/builders/AccumulatorsPickN.java

@@ -9,26 +9,26 @@
 import com.mongodb.client.MongoClient;
 import com.mongodb.client.MongoClients;
 import com.mongodb.client.MongoCollection;
-import com.mongodb.client.MongoDatabase;
-import com.mongodb.client.model.Accumulators;
-import com.mongodb.client.model.Aggregates;
-import com.mongodb.client.model.Sorts;
+import static com.mongodb.client.model.Accumulators.*;
+import static com.mongodb.client.model.Aggregates.*;
+import static com.mongodb.client.model.Sorts.*;
+import static java.util.Arrays.asList;
 
 public class AccumulatorsPickN {
     private static final String CONNECTION_URI = "<your connection URI>";
 
     private static void runAggregation(MongoCollection<Document> collection, Bson ...stages) {
         System.out.println("aggregateStages: " + Arrays.toString(stages));
         System.out.println("=== [ Result ] ============================================");
-        collection.aggregate(Arrays.asList(stages)).forEach(result -> System.out.println(result));
+        collection.aggregate(asList(stages)).forEach(result -> System.out.println(result));
     }
 
     private static Bson createMinNStage() {
         return
                 // begin minN accumulator
-                Aggregates.group(
+                group(
                         "$year",
-                        Accumulators.minN(
+                        minN(
                                 "lowest_three_ratings",
                                 new BsonString("$imdb.rating"),
                                 3
@@ -38,9 +38,9 @@ private static Bson createMinNStage() {
     private static Bson createnMaxNStage() {
         return
                 // begin maxN accumulator
-                Aggregates.group(
+                group(
                         "$year",
-                        Accumulators.maxN(
+                        maxN(
                                 "highest_two_ratings",
                                 new BsonString("$imdb.rating"),
                                 2
@@ -50,9 +50,9 @@ private static Bson createnMaxNStage() {
     private static Bson createFirstNStage() {
         return
                 // begin firstN accumulator
-                Aggregates.group(
+                group(
                         "$year",
-                        Accumulators.firstN(
+                        firstN(
                                 "first_four_movies",
                                 new BsonString("$title"),
                                 4
@@ -62,9 +62,9 @@ private static Bson createFirstNStage() {
     private static Bson createLastNStage() {
         return
                 // begin lastN accumulator
-                Aggregates.group(
+                group(
                         "$year",
-                        Accumulators.lastN(
+                        lastN(
                                 "last_three_movies",
                                 new BsonString("$title"),
                                 3
@@ -74,50 +74,50 @@ private static Bson createLastNStage() {
     private static Bson createTopStage() {
         return
                 // begin top accumulator
-                Aggregates.group(
+                group(
                         "$year", 
-                        Accumulators.top(
+                        top(
                                 "top_rated_movie",
-                                Sorts.descending("imdb.rating"),
-                                Arrays.asList(new BsonString("$title"), new BsonString("$imdb.rating"))
+                                descending("imdb.rating"),
+                                asList(new BsonString("$title"), new BsonString("$imdb.rating"))
                                 ));
                 // end top accumulator
     }
 
     private static Bson createTopNStage() {
         return
                 // begin topN accumulator
-                Aggregates.group(
+                group(
                         "$year", 
-                        Accumulators.topN(
+                        topN(
                                 "longest_three_movies",
-                                Sorts.descending("runtime"),
-                                Arrays.asList(new BsonString("$title"), new BsonString("$runtime")),
+                                descending("runtime"),
+                                asList(new BsonString("$title"), new BsonString("$runtime")),
                                 3
                                 ));
                 // end topN accumulator
     }
     private static Bson createBottomStage() {
         return 
                 // begin bottom accumulator
-                Aggregates.group(
+                group(
                         "$year", 
-                        Accumulators.bottom(
+                        bottom(
                                 "shortest_movies",
-                                Sorts.descending("runtime"),
-                                Arrays.asList(new BsonString("$title"), new BsonString("$runtime"))
+                                descending("runtime"),
+                                asList(new BsonString("$title"), new BsonString("$runtime"))
                                 ));
                 // end bottom accumulator;
     }
     private static Bson createBottomNStage() {
         return 
                 // begin bottomN accumulator
-                Aggregates.group(
+                group(
                         "$year", 
-                        Accumulators.bottomN(
+                        bottomN(
                                 "lowest_rated_two_movies",
-                                Sorts.descending("imdb.rating"),
-                                Arrays.asList(new BsonString("$title"), new BsonString("$imdb.rating")),
+                                descending("imdb.rating"),
+                                asList(new BsonString("$title"), new BsonString("$imdb.rating")),
                                 2
                                 ));
                 // end bottomN accumulator;

source/includes/fundamentals/code-snippets/builders/AggregateDensify.java

@@ -0,0 +1,54 @@
+package fundamentals.builders;
+
+import java.util.Arrays;
+
+import org.bson.BsonArray;
+import org.bson.Document;
+import org.bson.conversions.Bson;
+
+import com.mongodb.client.MongoClient;
+import com.mongodb.client.MongoClients;
+import com.mongodb.client.MongoCollection;
+import com.mongodb.client.model.Aggregates;
+import com.mongodb.client.model.Filters;
+import com.mongodb.client.model.MongoTimeUnit;
+import com.mongodb.client.model.densify.DensifyOptions;
+import com.mongodb.client.model.densify.DensifyRange;
+
+public class AggregateDensify {
+    private static final String CONNECTION_URI = "<your connection URI>";
+    
+    private static void runAggregation(MongoCollection<Document> collection, Bson ...stages) {
+        System.out.println("aggregateStages: " + Arrays.toString(stages));
+        System.out.println("=== [ Result ] ============================================");
+        collection.aggregate(Arrays.asList(stages)).forEach(result -> System.out.println(result));
+    }
+    
+    // Narrows down the data in the sample_weatherdata.data namespace
+    private static Bson createMatchStage() {
+        return Aggregates.match(Filters.eq("position.coordinates", BsonArray.parse("[-47.9, 47.6]")));
+    }
+    
+    
+    private static Bson createDensifyStage() throws Exception {
+        return Aggregates.
+                // begin densify aggregate
+                densify(
+                        "ts", 
+                        DensifyRange.partitionRangeWithStep(15, MongoTimeUnit.MINUTE),
+                        DensifyOptions.densifyOptions().partitionByFields("position.coordinates"));
+                // end densify aggregate
+    }
+    
+    public static void main(String[] args) {
+        try (MongoClient mongoClient = MongoClients.create(CONNECTION_URI)) {
+            MongoCollection<Document> collection = mongoClient.getDatabase("sample_weatherdata").getCollection("data");
+            
+             runAggregation(collection, createMatchStage(), createDensifyStage()); 
+        } catch (Exception e) {
+            System.err.println(e);
+        }
+
+    }
+
+}

source/whats-new.txt

@@ -78,7 +78,8 @@ New features of the 4.7 driver release include:
 
 - Added builder API methods for additional aggregation stages
   including :pipeline:`$search`/:pipeline:`$searchMeta` (Atlas only),
-  :pipeline:`$densify`, and :pipeline:`$fill`.
+  :pipeline:`$densify`, and :pipeline:`$fill`. Learn more about these
+  methods on the :ref:`Aggregates Builder <aggregates-builders>` page.
 
 - Added the ``BsonExtraElements`` annotation that can be used with POJO encoding
   and decoding. ``BsonExtraElements`` enables decoding objects that may receive