Package com.mongodb.client.model

Class WindowedComputations

  • @Beta
public final class WindowedComputations
extends Object
    Builders for windowed computations used in the $setWindowFields pipeline stage of an aggregation pipeline. Each windowed computation is a triple:
    • A window function. Some functions require documents in a window to be sorted (see sortBy in Aggregates.setWindowFields(Object, Bson, List)).
    • An optional window, a.k.a. frame. Specifying null window is equivalent to specifying an unbounded window, i.e., a window with both ends specified as Windows.Bound.UNBOUNDED. Some window functions require to specify an explicit unbounded window instead of specifying null.
    • A path to an output field to be computed by the window function over the window.
    A windowed computation is similar to an accumulator but does not result in folding documents constituting the window into a single document.
    Since:
    4.3
    MongoDB documentation
    Field paths
    Since server release
    5.0

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <TExpression>
      WindowedComputation      		 addToSet​(String path, TExpression expression, Window window)
      Builds a computation that adds the evaluation results of the expression over the window to a BSON Array and excludes duplicates.
      static <TExpression>
      WindowedComputation      		 avg​(String path, TExpression expression, Window window)
      Builds a computation of the average of the evaluation results of the expression over the window.
      static WindowedComputation count​(String path, Window window)
      Builds a computation of the number of documents in the window.
      static <TExpression>
      WindowedComputation      		 covariancePop​(String path, TExpression expression1, TExpression expression2, Window window)
      Builds a computation of the population covariance between the evaluation results of the two expressions over the window.
      static <TExpression>
      WindowedComputation      		 covarianceSamp​(String path, TExpression expression1, TExpression expression2, Window window)
      Builds a computation of the sample covariance between the evaluation results of the two expressions over the window.
      static WindowedComputation denseRank​(String path)
      Builds a computation of the dense rank of each document in its partition.
      static <TExpression>
      WindowedComputation      		 derivative​(String path, TExpression expression, Window window)
      Builds a computation of the time derivative by subtracting the evaluation result of the expression against the last document and the first document in the window and dividing it by the difference in the values of the sortBy field of the respective documents.
      static WindowedComputation documentNumber​(String path)
      Builds a computation of the order number of each document in its partition.
      static <TExpression>
      WindowedComputation      		 expMovingAvg​(String path, TExpression expression, double alpha)
      Builds a computation of the exponential moving average of the evaluation results of the expression over the half-bounded window [Windows.Bound.UNBOUNDED, Windows.Bound.CURRENT], with alpha representing the degree of weighting decrease.
      static <TExpression>
      WindowedComputation      		 expMovingAvg​(String path, TExpression expression, int n)
      Builds a computation of the exponential moving average of the evaluation results of the expression over a window that includes n - 1 documents preceding the current document and the current document, with more weight on documents closer to the current one.
      static <TExpression>
      WindowedComputation      		 first​(String path, TExpression expression, Window window)
      Builds a computation of the evaluation result of the expression against the first document in the window.
      static <TExpression>
      WindowedComputation      		 integral​(String path, TExpression expression, Window window)
      Builds a computation of the approximate integral of a function that maps values of the sortBy field to evaluation results of the expression against the same document.
      static <TExpression>
      WindowedComputation      		 last​(String path, TExpression expression, Window window)
      Builds a computation of the evaluation result of the expression against the last document in the window.
      static <TExpression>
      WindowedComputation      		 max​(String path, TExpression expression, Window window)
      Builds a computation of the highest of the evaluation results of the expression over the window.
      static <TExpression>
      WindowedComputation      		 min​(String path, TExpression expression, Window window)
      Builds a computation of the lowest of the evaluation results of the expression over the window.
      static WindowedComputation of​(BsonField windowedComputation)
      Creates a windowed computation from a document field in situations when there is no builder method that better satisfies your needs.
      static <TExpression>
      WindowedComputation      		 push​(String path, TExpression expression, Window window)
      Builds a computation that adds the evaluation results of the expression over the window to a BSON Array.
      static WindowedComputation rank​(String path)
      Builds a computation of the rank of each document in its partition.
      static <TExpression>
      WindowedComputation      		 shift​(String path, TExpression expression, TExpression defaultExpression, int by)
      Builds a computation of the evaluation result of the expression for the document whose position is shifted by the given amount relative to the current document.
      static <TExpression>
      WindowedComputation      		 stdDevPop​(String path, TExpression expression, Window window)
      Builds a computation of the population standard deviation of the evaluation results of the expression over the window.
      static <TExpression>
      WindowedComputation      		 stdDevSamp​(String path, TExpression expression, Window window)
      Builds a computation of the sample standard deviation of the evaluation results of the expression over the window.
      static <TExpression>
      WindowedComputation      		 sum​(String path, TExpression expression, Window window)
      Builds a computation of the sum of the evaluation results of the expression over the window.
      static <TExpression>
      WindowedComputation      		 timeDerivative​(String path, TExpression expression, Window window, MongoTimeUnit unit)
      Builds a computation of the time derivative by subtracting the evaluation result of the expression against the last document and the first document in the window and dividing it by the difference in the BSON Date values of the sortBy field of the respective documents.
      static <TExpression>
      WindowedComputation      		 timeIntegral​(String path, TExpression expression, Window window, MongoTimeUnit unit)
      Builds a computation of the approximate integral of a function that maps BSON Date values of the sortBy field to evaluation results of the expression against the same document.

    • Method Detail

      • of

        public static WindowedComputation of​(BsonField windowedComputation)
        Creates a windowed computation from a document field in situations when there is no builder method that better satisfies your needs. This method cannot be used to validate the document field syntax.

        Example
        The following code creates two functionally equivalent windowed computations, though they may not be equal. 

        
  Window pastWeek = Windows.timeRange(-1, MongoTimeUnit.WEEK, Windows.Bound.CURRENT);
  WindowedComputation pastWeekExpenses1 = WindowedComputations.sum("pastWeekExpenses", "$expenses", pastWeek);
  WindowedComputation pastWeekExpenses2 = WindowedComputations.of(
          new BsonField("pastWeekExpenses", new Document("$sum", "$expenses")
                  .append("window", pastWeek.toBsonDocument())));
        Parameters:
        windowedComputation - A document field representing the required windowed computation.
        Returns:
        The constructed windowed computation.

      • sum

        public static <TExpression> WindowedComputation sum​(String path,
                                                    TExpression expression,
                                                    @Nullable
                                                    Window window)
        Builds a computation of the sum of the evaluation results of the expression over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $sum

      • avg

        public static <TExpression> WindowedComputation avg​(String path,
                                                    TExpression expression,
                                                    @Nullable
                                                    Window window)
        Builds a computation of the average of the evaluation results of the expression over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $avg

      • stdDevSamp

        public static <TExpression> WindowedComputation stdDevSamp​(String path,
                                                           TExpression expression,
                                                           @Nullable
                                                           Window window)
        Builds a computation of the sample standard deviation of the evaluation results of the expression over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $stdDevSamp

      • stdDevPop

        public static <TExpression> WindowedComputation stdDevPop​(String path,
                                                          TExpression expression,
                                                          @Nullable
                                                          Window window)
        Builds a computation of the population standard deviation of the evaluation results of the expression over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $stdDevPop

      • min

        public static <TExpression> WindowedComputation min​(String path,
                                                    TExpression expression,
                                                    @Nullable
                                                    Window window)
        Builds a computation of the lowest of the evaluation results of the expression over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $min

      • max

        public static <TExpression> WindowedComputation max​(String path,
                                                    TExpression expression,
                                                    @Nullable
                                                    Window window)
        Builds a computation of the highest of the evaluation results of the expression over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $max

      • count

        public static WindowedComputation count​(String path,
                                        @Nullable
                                        Window window)
        Builds a computation of the number of documents in the window.
        Parameters:
        path - The output field path.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $count

      • derivative

        public static <TExpression> WindowedComputation derivative​(String path,
                                                           TExpression expression,
                                                           Window window)
        Builds a computation of the time derivative by subtracting the evaluation result of the expression against the last document and the first document in the window and dividing it by the difference in the values of the sortBy field of the respective documents. Other documents in the window have no effect on the computation.

        Sorting is required.

        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $derivative

      • integral

        public static <TExpression> WindowedComputation integral​(String path,
                                                         TExpression expression,
                                                         Window window)
        Builds a computation of the approximate integral of a function that maps values of the sortBy field to evaluation results of the expression against the same document. The limits of integration match the window bounds. The approximation is done by using the trapezoidal rule.

        Sorting is required.

        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $integral

      • covarianceSamp

        public static <TExpression> WindowedComputation covarianceSamp​(String path,
                                                               TExpression expression1,
                                                               TExpression expression2,
                                                               @Nullable
                                                               Window window)
        Builds a computation of the sample covariance between the evaluation results of the two expressions over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression1 - The first expression.
        expression2 - The second expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $covarianceSamp

      • covariancePop

        public static <TExpression> WindowedComputation covariancePop​(String path,
                                                              TExpression expression1,
                                                              TExpression expression2,
                                                              @Nullable
                                                              Window window)
        Builds a computation of the population covariance between the evaluation results of the two expressions over the window.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression1 - The first expression.
        expression2 - The second expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $covariancePop

      • expMovingAvg

        public static <TExpression> WindowedComputation expMovingAvg​(String path,
                                                             TExpression expression,
                                                             int n)
        Builds a computation of the exponential moving average of the evaluation results of the expression over a window that includes n - 1 documents preceding the current document and the current document, with more weight on documents closer to the current one.

        Sorting is required.

        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        n - Must be positive.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $expMovingAvg

      • expMovingAvg

        public static <TExpression> WindowedComputation expMovingAvg​(String path,
                                                             TExpression expression,
                                                             double alpha)
        Builds a computation of the exponential moving average of the evaluation results of the expression over the half-bounded window [Windows.Bound.UNBOUNDED, Windows.Bound.CURRENT], with alpha representing the degree of weighting decrease.

        Sorting is required.

        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        alpha - A parameter specifying how fast weighting decrease happens. A higher alpha discounts older observations faster. Must belong to the interval (0, 1).
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $expMovingAvg

      • push

        public static <TExpression> WindowedComputation push​(String path,
                                                     TExpression expression,
                                                     @Nullable
                                                     Window window)
        Builds a computation that adds the evaluation results of the expression over the window to a BSON Array. Order within the array is guaranteed if sortBy is specified.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $push

      • addToSet

        public static <TExpression> WindowedComputation addToSet​(String path,
                                                         TExpression expression,
                                                         @Nullable
                                                         Window window)
        Builds a computation that adds the evaluation results of the expression over the window to a BSON Array and excludes duplicates. Order within the array is not specified.
        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $addToSet

      • first

        public static <TExpression> WindowedComputation first​(String path,
                                                      TExpression expression,
                                                      @Nullable
                                                      Window window)
        Builds a computation of the evaluation result of the expression against the first document in the window.

        Sorting is required.

        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $first

      • last

        public static <TExpression> WindowedComputation last​(String path,
                                                     TExpression expression,
                                                     @Nullable
                                                     Window window)
        Builds a computation of the evaluation result of the expression against the last document in the window.

        Sorting is required.

        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        window - The window.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $last

      • shift

        public static <TExpression> WindowedComputation shift​(String path,
                                                      TExpression expression,
                                                      @Nullable
                                                      TExpression defaultExpression,
                                                      int by)
        Builds a computation of the evaluation result of the expression for the document whose position is shifted by the given amount relative to the current document. If the shifted document is outside of the partition containing the current document, then the defaultExpression is used instead of the expression.

        Sorting is required.

        Type Parameters:
        TExpression - The expression type.
        Parameters:
        path - The output field path.
        expression - The expression.
        defaultExpression - The default expression. If null, then the default expression is evaluated to BSON null. Must evaluate to a constant value.
        by - The shift specified similarly to rules for window bounds:
        • 0 means the current document;
        • a negative value refers to the document preceding the current one;
        • a positive value refers to the document following the current one.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $shift

      • documentNumber

        public static WindowedComputation documentNumber​(String path)
        Builds a computation of the order number of each document in its partition.

        Sorting is required.

        Parameters:
        path - The output field path.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $documentNumber

      • rank

        public static WindowedComputation rank​(String path)
        Builds a computation of the rank of each document in its partition. Documents with the same value(s) of the sortBy fields result in the same ranking and result in gaps in the returned ranks. For example, a partition with the sequence [1, 3, 3, 5] representing the values of the single sortBy field produces the following sequence of rank values: [1, 2, 2, 4].

        Sorting is required.

        Parameters:
        path - The output field path.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $rank

      • denseRank

        public static WindowedComputation denseRank​(String path)
        Builds a computation of the dense rank of each document in its partition. Documents with the same value(s) of the sortBy fields result in the same ranking but do not result in gaps in the returned ranks. For example, a partition with the sequence [1, 3, 3, 5] representing the values of the single sortBy field produces the following sequence of rank values: [1, 2, 2, 3].

        Sorting is required.

        Parameters:
        path - The output field path.
        Returns:
        The constructed windowed computation.
        MongoDB documentation
        $denseRank