Package dev.morphia.aggregation.stages

Class Bucket

  • public class Bucket
extends Stage
    Categorizes incoming documents into groups, called buckets, based on a specified expression and bucket boundaries.

    Each bucket is represented as a document in the output. The document for each bucket contains an _id field, whose value specifies the inclusive lower bound of the bucket and a count field that contains the number of documents in the bucket. The count field is included by default when the output is not specified.

    $bucket only produces output documents for buckets that contain at least one input document.

    • Constructor Detail

      • Bucket

        protected Bucket()

    • Method Detail

      • bucket

        public static Bucket bucket()
        Creates a new bucket stage
        Returns:
        the new stage
        Since:
        2.2

      • of

        @Deprecated(forRemoval=true)
public static Bucket of()
        Deprecated, for removal: This API element is subject to removal in a future version.
        use bucket()
        Creates a new bucket stage
        Returns:
        the new stage

      • boundaries

        public Bucket boundaries​(dev.morphia.aggregation.expressions.impls.Expression... boundaries)
        An array of values based on the groupBy expression that specify the boundaries for each bucket. Each adjacent pair of values acts as the inclusive lower boundary and the exclusive upper boundary for the bucket. You must specify at least two boundaries.

        The specified values must be in ascending order and all of the same type.

        Parameters:
        boundaries - the boundaries
        Returns:
        this

      • defaultValue

        public Bucket defaultValue​(Object defaultValue)
        Optional. A literal that specifies the _id of an additional bucket that contains all documents whose groupBy expression result does not fall into a bucket specified by boundaries.

        If unspecified, each input document must resolve the groupBy expression to a value within one of the bucket ranges specified by boundaries or the operation throws an error.

        Parameters:
        defaultValue - the default value
        Returns:
        this

      • getBoundaries

        @MorphiaInternal
public dev.morphia.aggregation.expressions.impls.ExpressionList getBoundaries()
        Returns:
        the boundaries
        Developer note.
        This is an internal item. Its function and presence are subject to change without warning. Its use is highly discouraged.

      • getDefaultValue

        @MorphiaInternal
public Object getDefaultValue()
        Returns:
        the default value
        Developer note.
        This is an internal item. Its function and presence are subject to change without warning. Its use is highly discouraged.

      • getGroupBy

        @MorphiaInternal
public dev.morphia.aggregation.expressions.impls.Expression getGroupBy()
        Returns:
        the group by expression
        Developer note.
        This is an internal item. Its function and presence are subject to change without warning. Its use is highly discouraged.

      • getOutput

        @Nullable
@MorphiaInternal
public dev.morphia.aggregation.expressions.impls.DocumentExpression getOutput()
        Returns:
        the output document
        Developer note.
        This is an internal item. Its function and presence are subject to change without warning. Its use is highly discouraged.

      • groupBy

        public Bucket groupBy​(dev.morphia.aggregation.expressions.impls.Expression groupBy)
        An expression to group documents by. To specify a field path, prefix the field name with a dollar sign $ and enclose it in quotes.

        Unless $bucket includes a default specification, each input document must resolve the groupBy field path or expression to a value that falls within one of the ranges specified by the boundaries.

        Parameters:
        groupBy - the grouping expression
        Returns:
        this

      • outputField

        public Bucket outputField​(String name,
                          dev.morphia.aggregation.expressions.impls.Expression value)
        Adds a field to the document that specifies the fields to include in the output documents in addition to the _id field. To specify the field to include, you must use accumulator expressions.
        Parameters:
        name - the new field name
        value - the value expression
        Returns:
        this