com.allanbank.mongodb.builder

Class Aggregate.Builder

java.lang.Object

com.allanbank.mongodb.builder.Aggregate.Builder

Enclosing class:

Aggregate

public static class Aggregate.Builder
extends Object

Builder provides the ability to construct aggregate command pipelines.

Methods are provided for all existing pipeline operators and generic step(java.lang.String, com.allanbank.mongodb.bson.DocumentAssignable) methods are provided to support future pipeline operators while in development or before the driver is updated.

This builder is intended to be used with the various support classes including the Expressions library. For example:

 
  import static com.allanbank.mongodb.builder.AggregationGroupField.set;
  import static com.allanbank.mongodb.builder.AggregationGroupId.id;
  import static com.allanbank.mongodb.builder.AggregationProjectFields.includeWithoutId;
  import static com.allanbank.mongodb.builder.QueryBuilder.where;
  import static com.allanbank.mongodb.builder.Sort.asc;
  import static com.allanbank.mongodb.builder.Sort.desc;
  import static com.allanbank.mongodb.builder.expression.Expressions.field;
  import static com.allanbank.mongodb.builder.expression.Expressions.set;
  
  DocumentBuilder b1 = BuilderFactory.start();
  DocumentBuilder b2 = BuilderFactory.start();
  Aggregate.Builder builder = new Aggregate.Builder();
  
  builder.match(where("state").notEqualTo("NZ"))
          .group(id().addField("state")
                     .addField("city"),
                 set("pop").sum("pop"))
          .sort(asc("pop"))
          .group(id("_id.state"), 
                 set("biggestcity").last("_id.city"),
                 set("biggestpop").last("pop"),
                 set("smallestcity").first("_id.city"),
                 set("smallestpop").first("pop"))
          .project(
                  includeWithoutId(),
                  set("state", field("_id")),
                  set("biggestCity",
                          b1.add(set("name", field("biggestcity"))).add(
                                  set("pop", field("biggestpop")))),
                  set("smallestCity",
                          b2.add(set("name", field("smallestcity"))).add(
                                  set("pop", field("smallestpop")))))
          .sort(desc("biggestCity.pop"));
 
 

See Also:

Example Inspired By

API Notice:

This class is part of the driver's API. Public and protected members will be deprecated for at least 1 non-bugfix release (version numbers are <major>.<minor>.<bugfix>) before being removed or modified.

Copyright ©:

2012-2013, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields

Modifier and Type	Field and Description
protected ArrayBuilder	myPipeline The pipeline of operations to be applied.
protected ReadPreference	myReadPreference The read preference to use.

Constructor Summary

Constructors

Constructor and Description
Aggregate.Builder() Creates a new Builder.

Method Summary

Methods

Modifier and Type	Method and Description
Aggregate	build() Constructs a new Aggregate object from the state of the builder.
Aggregate.Builder	geoNear(AggregationGeoNear.Builder geoNear) Adds a $geoNear operation to the pipeline to select documents for the aggregation pipeline based on their relative location to a set point.
Aggregate.Builder	geoNear(AggregationGeoNear geoNear) Adds a $geoNear operation to the pipeline to select documents for the aggregation pipeline based on their relative location to a set point.
Aggregate.Builder	group(AggregationGroupId.Builder id, AggregationGroupField... aggregations) Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.
Aggregate.Builder	group(AggregationGroupId id, AggregationGroupField... aggregations) Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.
Aggregate.Builder	group(DocumentAssignable aggregations) Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.
Aggregate.Builder	group(DocumentAssignable id, AggregationGroupField... aggregations) Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.
Aggregate.Builder	limit(int numberOfDocuments) Adds a $limit operation to the pipeline to stop producing documents passing this point in the pipeline once the limit of documents is reached.
Aggregate.Builder	limit(long numberOfDocuments) Adds a $limit operation to the pipeline to stop producing documents passing this point in the pipeline once the limit of documents is reached.
Aggregate.Builder	match(DocumentAssignable query) Adds a $match operation to the pipeline to filter documents passing this point in the pipeline.
Aggregate.Builder	project(AggregationProjectFields fields, Element... elements) Adds a $project operation to the pipeline to create a projection of the documents passing this point in the pipeline.
Aggregate.Builder	project(DocumentAssignable projection) Adds a $project operation to the pipeline to create a projection of the documents passing this point in the pipeline.
Aggregate.Builder	reset() Resets the builder back to an empty pipeline.
Aggregate.Builder	setReadPreference(ReadPreference readPreference) Sets the ReadPreference specifying which servers may be used to execute the aggregation.
Aggregate.Builder	skip(int numberOfDocuments) Adds a $skip operation to the pipeline to skip the specified number of documents before allowing any document past this point in the pipeline.
Aggregate.Builder	skip(long numberOfDocuments) Adds a $skip operation to the pipeline to skip the specified number of documents before allowing any document past this point in the pipeline.
Aggregate.Builder	sort(IntegerElement... sortFields) Adds a $sort operation to sort the documents passing this point based on the sort specification provided.
Aggregate.Builder	sort(String... sortFields) Adds a $sort operation to sort the documents passing this point based on the sort fields provides in ascending order.
Aggregate.Builder	step(String operator, DocumentAssignable stepDocument) Adds a generic step to the builder's pipeline.
Aggregate.Builder	step(String operator, double value) Adds a generic step to the builder's pipeline.
Aggregate.Builder	step(String operator, Element... elements) Adds a generic step to the builder's pipeline.
Aggregate.Builder	step(String operator, int value) Adds a generic step to the builder's pipeline.
Aggregate.Builder	step(String operator, List<Element> elements) Adds a generic step to the builder's pipeline.
Aggregate.Builder	step(String operator, long value) Adds a generic step to the builder's pipeline.
Aggregate.Builder	step(String operator, String value) Adds a generic step to the builder's pipeline.
Aggregate.Builder	unwind(String fieldName) Adds a $unwind operation generate a document for each element of the specified array field with the array replaced with the value of the element.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

myPipeline

protected final ArrayBuilder myPipeline

The pipeline of operations to be applied.

myReadPreference

protected ReadPreference myReadPreference

The read preference to use.

Constructor Detail

Aggregate.Builder

public Aggregate.Builder()

Creates a new Builder.

Method Detail

build

public Aggregate build()

Constructs a new Aggregate object from the state of the builder.

Returns:

The new Aggregate object.

geoNear

public Aggregate.Builder geoNear(AggregationGeoNear geoNear)

Adds a $geoNear operation to the pipeline to select documents for the aggregation pipeline based on their relative location to a set point. The $geoNear must be the first option in the aggregation pipeline.

 
 import com.allanbank.mongodb.builder.AggregationGeoNear;
 
 Aggregate.Builder builder = new Aggregate.Builder();
 builder.geoNear( AggregationGeoNear.builder()
           .location( new Point( 1, 2 ) )
           .distanceLocationField( "stats.distance" )
           .limit( 5 ).build() );
 
 

Parameters:

geoNear - The options for the GeoNear operation.

Returns:

This builder for chaining method calls.

Since:

MongoDB 2.4

geoNear

public Aggregate.Builder geoNear(AggregationGeoNear.Builder geoNear)

Adds a $geoNear operation to the pipeline to select documents for the aggregation pipeline based on their relative location to a set point. The $geoNear must be the first option in the aggregation pipeline.

 
 import com.allanbank.mongodb.builder.AggregationGeoNear;
 
 Aggregate.Builder builder = new Aggregate.Builder();
 builder.geoNear( AggregationGeoNear.builder()
           .location( new Point( 1, 2 ) )
           .distanceLocationField( "stats.distance" )
           .limit( 5 ) );
 
 

Parameters:

geoNear - The options for the GeoNear operation.

Returns:

This builder for chaining method calls.

Since:

MongoDB 2.4

group

public Aggregate.Builder group(AggregationGroupId id,
                      AggregationGroupField... aggregations)

Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.

This method is intended to construct groups with simple dynamic or static id documents.

 
 import static com.allanbank.mongodb.builder.AggregationGroupId.id;
 import static com.allanbank.mongodb.builder.AggregationGroupField.set;
 
 Aggregate.Builder builder = new Aggregate.Builder();
 builder.group(
           id("$field1"),
           set("resultField1").uniqueValuesOf("$field2"),
           set("resultField2").max("$field3"),
           set("sum").sum("$field4") );
 
 

Parameters:

id - The builder for the _id field to specify unique groups.

aggregations - The specification for the group id and what fields to aggregate in the form of a document.

Returns:

This builder for chaining method calls.

group

public Aggregate.Builder group(AggregationGroupId.Builder id,
                      AggregationGroupField... aggregations)

Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.

This method is intended to construct groups with complex dynamic or static id documents. The AggregationGroupId.Builder implements the DocumentBuilder for construction of arbitrary complex _id documents.

 
 import static com.allanbank.mongodb.builder.AggregationGroupId.id;
 import static com.allanbank.mongodb.builder.AggregationGroupField.set;
 
 Aggregate.Builder builder = new Aggregate.Builder();
 builder.group(
           id().addField("$field1").addField("$field2"),
           set("resultField1").uniqueValuesOf("$field3"),
           set("resultField2").first("$field4"),
           set("count").count() );
 
 

Parameters:

id - The builder for the _id field to specify unique groups.

aggregations - The specification for the group id and what fields to aggregate in the form of a document.

Returns:

This builder for chaining method calls.

group

public Aggregate.Builder group(DocumentAssignable aggregations)

Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.

Parameters:

aggregations - The specification for the group id and what fields to aggregate in the form of a document.

Returns:

This builder for chaining method calls.

group

public Aggregate.Builder group(DocumentAssignable id,
                      AggregationGroupField... aggregations)

Adds a $group operation to the pipeline to aggregate documents passing this point in the pipeline into a group of documents.

This method is intended to construct groups with complex dynamic or static id documents. The AggregationGroupId.Builder implements the DocumentBuilder for construction of arbitrary complex _id documents.

 
 import static com.allanbank.mongodb.builder.AggregationGroupId.id;
 import static com.allanbank.mongodb.builder.AggregationGroupField.set;
 
 Aggregate.Builder builder = new Aggregate.Builder();
 builder.group(
           id().addInteger("i", 1),
           set("resultField1").uniqueValuesOf("$field3"),
           set("resultField2").first("$field4"),
           set("count").count() );
 
 

Parameters:

id - The builder for the _id field to specify unique groups.

aggregations - The specification for the group id and what fields to aggregate in the form of a document.

Returns:

This builder for chaining method calls.

limit

public Aggregate.Builder limit(int numberOfDocuments)

Adds a $limit operation to the pipeline to stop producing documents passing this point in the pipeline once the limit of documents is reached.

Parameters:

numberOfDocuments - The number of documents to allow past this point in the pipeline.

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $limit

limit

public Aggregate.Builder limit(long numberOfDocuments)

Adds a $limit operation to the pipeline to stop producing documents passing this point in the pipeline once the limit of documents is reached.

Parameters:

numberOfDocuments - The number of documents to allow past this point in the pipeline.

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $limit

match

public Aggregate.Builder match(DocumentAssignable query)

Adds a $match operation to the pipeline to filter documents passing this point in the pipeline.

This method may be used with the QueryBuilder to easily specify the criteria to match against.

 
 import static com.allanbank.mongodb.builder.QueryBuilder.where
 
 Aggregate.Builder builder = new Aggregate.Builder();
 
 builder.match( where("f").greaterThan(23).lessThan(42).and("g").lessThan(3) );
 ...
 
 

Parameters:

query - The query to match documents against.

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $match

project

public Aggregate.Builder project(AggregationProjectFields fields,
                        Element... elements)

Adds a $project operation to the pipeline to create a projection of the documents passing this point in the pipeline.

This method is intended to be used with the AggregationProjectFields and Expressions static helper methods.

 
 import static com.allanbank.mongodb.builder.AggregationProjectFields.include;
 import static com.allanbank.mongodb.builder.expression.Expressions.*;
 
 
 Aggregate.Builder builder = new Aggregate.Builder();
 ...
 builder.project(
         include("chr", "begin", "end", "calledPloidy"),
         set("window",
             multiply(
                 divide(
                     subtract(
                         field("begin"), 
                         mod(field("begin"), constant(interval))),
                     constant(interval)), 
                 constant(interval))));
 ...
 
 

Parameters:

fields - The fields to copy into the projected results.

elements - The computed elements based on Expressions.

Returns:

This builder for chaining method calls.

project

public Aggregate.Builder project(DocumentAssignable projection)

Adds a $project operation to the pipeline to create a projection of the documents passing this point in the pipeline.

Parameters:

projection - The specification for the projection to perform.

Returns:

This builder for chaining method calls.

reset

public Aggregate.Builder reset()

Resets the builder back to an empty pipeline.

Returns:

This builder for chaining method calls.

setReadPreference

public Aggregate.Builder setReadPreference(ReadPreference readPreference)

Sets the ReadPreference specifying which servers may be used to execute the aggregation.

If not set or set to null then the MongoCollection instance's ReadPreference will be used.

Parameters:

readPreference - The read preferences specifying which servers may be used.

Returns:

This builder for chaining method calls.

See Also:

MongoCollection.getReadPreference()

skip

public Aggregate.Builder skip(int numberOfDocuments)

Adds a $skip operation to the pipeline to skip the specified number of documents before allowing any document past this point in the pipeline.

Parameters:

numberOfDocuments - The number of documents to skip past before allowing any documents to pass this point in the pipeline.

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $skip

skip

public Aggregate.Builder skip(long numberOfDocuments)

Adds a $skip operation to the pipeline to skip the specified number of documents before allowing any document past this point in the pipeline.

Parameters:

numberOfDocuments - The number of documents to skip past before allowing any documents to pass this point in the pipeline.

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $skip

sort

public Aggregate.Builder sort(IntegerElement... sortFields)

Adds a $sort operation to sort the documents passing this point based on the sort specification provided.

This method is intended to be used with the Sort class's static methods:

 
 import static com.allanbank.mongodb.builder.Sort.asc;
 import static com.allanbank.mongodb.builder.Sort.desc;
 
 Aggregate.Builder builder = new Aggregate.Builder();
 
 builder.setSort( asc("f"), desc("g") );
 ...
 
 

Parameters:

sortFields - The sort fields to use.

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $sort

sort

public Aggregate.Builder sort(String... sortFields)

Adds a $sort operation to sort the documents passing this point based on the sort fields provides in ascending order.

Parameters:

sortFields - The sort fields to use in ascending order.

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $sort

step

public Aggregate.Builder step(String operator,
                     DocumentAssignable stepDocument)

Adds a generic step to the builder's pipeline.

Parameters:

operator - The operator to add to the pipeline.

stepDocument - The document containing the details of the step to apply.

Returns:

This builder for chaining method calls.

step

public Aggregate.Builder step(String operator,
                     double value)

Adds a generic step to the builder's pipeline.

Parameters:

operator - The operator to add to the pipeline.

value - The value for the operator.

Returns:

This builder for chaining method calls.

step

public Aggregate.Builder step(String operator,
                     Element... elements)

Adds a generic step to the builder's pipeline.

Parameters:

operator - The operator to add to the pipeline.

elements - The elements containing the details of the step to apply.

Returns:

This builder for chaining method calls.

step

public Aggregate.Builder step(String operator,
                     int value)

Adds a generic step to the builder's pipeline.

Parameters:

operator - The operator to add to the pipeline.

value - The value for the operator.

Returns:

This builder for chaining method calls.

step

public Aggregate.Builder step(String operator,
                     List<Element> elements)

Adds a generic step to the builder's pipeline.

Parameters:

operator - The operator to add to the pipeline.

elements - The elements containing the details of the step to apply.

Returns:

This builder for chaining method calls.

step

public Aggregate.Builder step(String operator,
                     long value)

Adds a generic step to the builder's pipeline.

Parameters:

operator - The operator to add to the pipeline.

value - The value for the operator.

Returns:

This builder for chaining method calls.

step

public Aggregate.Builder step(String operator,
                     String value)

Adds a generic step to the builder's pipeline.

Parameters:

operator - The operator to add to the pipeline.

value - The value for the operator.

Returns:

This builder for chaining method calls.

unwind

public Aggregate.Builder unwind(String fieldName)

Adds a $unwind operation generate a document for each element of the specified array field with the array replaced with the value of the element.

Parameters:

fieldName - The name of the array field within the document to unwind. This name must start with a '$'. If it does not a '$' will be prepended to the field name..

Returns:

This builder for chaining method calls.

See Also:

Aggregation Framework Operators - $unwind