Package com.mongodb.client.model

Class WindowedComputations

java.lang.Object
com.mongodb.client.model.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

    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.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • 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

    • timeDerivative

      public 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. 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.
      unit - The desired time unit for the divisor. Allowed values are: MongoTimeUnit.WEEK, MongoTimeUnit.DAY, MongoTimeUnit.HOUR, MongoTimeUnit.MINUTE, MongoTimeUnit.SECOND, MongoTimeUnit.MILLISECOND.
      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

    • timeIntegral

      public 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. 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.
      unit - The desired time unit for the divisor. Allowed values are: MongoTimeUnit.WEEK, MongoTimeUnit.DAY, MongoTimeUnit.HOUR, MongoTimeUnit.MINUTE, MongoTimeUnit.SECOND, MongoTimeUnit.MILLISECOND.
      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