Clone wiki

mongo-java-aggregate / Home


The MongoDB Java Driver Aggregate extension is an extension to the MongoDB Java Driver to allow for easier syntax for working with the Aggregation Framework. It is available for free under the Apache License, Version 2.0.


Detailed API documentation can be found in the JavaDocs (available via Maven Central, in the source or online via CI). Installation directions and usage examples follow below.


Before you can use the library, you'll need to obtain a copy of the JAR and add it to your classpath. Since the library is available in Maven Central, in most cases that should mean adding a declaration of the dependency to your build file. After selecting a version, this page has examples of common forms of this declaration. If your build system doesn't support loading libraries from Maven Central, you can download the JAR from here and add it to your classpath manually.

Basic Usage

For a basic example of usage, consider the first example from the Aggregation Framework documentation. It uses a collection of documents named articles using the following format:

 title : "this is my title" ,
 author : "bob" ,
 posted : new Date () ,
 pageViews : 5 ,
 tags : [ "fun" , "good" , "fun" ] ,
 comments : [
             { author :"joe" , text : "this is cool" } ,
             { author :"sam" , text : "this is bad" }
 other : { foo : 5 }

The example uses the aggregation framework to create a set of author names grouped by tags applied to an article. In JavaScript, this looks like:

  { $project : {
     author : 1,
     tags : 1,
  } },
  { $unwind : "$tags" },
  { $group : {
     _id : { tags : "$tags" },
     authors : { $addToSet : "$author" }
  } }

In Java (without this library), this aggregation looks like this (omitting imports and connecting to the database for brevity):

DBCollection collection = db.getCollection("articles");
AggregationOutput output = collection.aggregate(
    new BasicDBObject("$project", new BasicDBObject()
        .append("author", 1)
        .append("tags", 1)
    new BasicDBObject("$unwind", "$tags"),
    new BasicDBObject("$group", new BasicDBObject()
        .append("_id", new BasicDBObject("tags", "$tags"))
        .append("authors", new BasicDBObject("$addToSet", "$author"))

Using this library, you would instead write it like this:

DBCollection collection = db.getCollection("articles");
AggregationOutput output = AggregateBuilder.aggregate(collection)
        "author", 1,
        "tags", 1)
        .put("_id").to(DBO.of("tags", "$tags"))

The key difference is using methods instead of string literals for the operators. This allows for IDE auto-completion, syntax checking, and context-relevant JavaDocs.

In languages with a more concise syntax for expressing maps, you can condense this example a bit further. In Groovy, this might look like:

def collection = db.getCollection('articles')
def output = ( AggregateBuilder.aggregate(collection)
    .project([author: 1, tags: 1])
        .put('_id').to([tags: '$tags'])

For more information on how to use the library, see Further Examples.