DOCSP-10258 window functions

Author: jason-price-mongodb

source/includes/covariance-behavior.rst

@@ -0,0 +1,33 @@
+- Ignores non-numeric values, ``null`` values, and missing fields in a
+  window.
+
+- If the window contains one document, returns ``null``.
+  (Compare to |covariance-method|, which returns |covariance-value| if
+  the window contains one document.)
+
+- If the window is empty, returns ``null``.
+
+- If the window contains a ``NaN`` value, returns ``NaN``.
+
+- If the window contains one or more ``Infinity`` value(s) that are
+  all positive or all negative, returns ``Infinity``. The returned
+  ``Infinity`` value has the same sign as the ``Infinity`` values in the
+  window.
+
+- If the window contains ``Infinity`` values with different signs,
+  returns ``NaN``.
+
+- If the window contains a ``decimal`` value, returns a ``decimal``
+  value.
+
+- If none of the previous points apply, returns a ``double`` value.
+
+The returned values in order of precedence are as follows:
+
+- ``NaN``
+
+- ``Infinity``
+
+- ``decimal``
+
+- ``double``

source/includes/expMovingAvg-N-or-alpha.rst

@@ -0,0 +1,2 @@
+You must specify either :ref:`N <expMovingAvg-N>` or :ref:`alpha
+<expMovingAvg-alpha>`. You cannot specify both.

source/includes/extracts-agg-operators.yaml

@@ -930,6 +930,8 @@ content: |
 ref: agg-operators-accumulators-group
 content: |
 
+   .. versionchanged:: 5.0
+
    .. list-table::
       :header-rows: 1
       :widths: 20 80
@@ -943,36 +945,62 @@ content: |
 
       * - :group:`$addToSet`
 
-        - Returns an array of *unique* expression values for each
-          group. Order of the array elements is undefined.
+        - Returns an array of *unique* expression values for each group.
+          Order of the array elements is undefined.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
 
       * - :group:`$avg`
 
         - Returns an average of numerical values. Ignores non-numeric values.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
       * - :group:`$count`
 
-        - Returns the count of the documents in the stage. May be used in
-          place of ``{ $sum : 1 }``.
+        - Returns the number of documents in a group.
+
+          Distinct from the :pipeline:`$count` pipeline stage.
+
+          .. versionadded:: 5.0
+
+             Available in :pipeline:`$group` and
+             :pipeline:`$setWindowFields` stages.
 
       * - :group:`$first`
 
         - Returns a value from the first document for each group. Order
-          is only defined if the documents are in a defined order.
+          is only defined if the documents are sorted.
           
           Distinct from the :expression:`$first` array operator.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
       * - :group:`$last`
 
         - Returns a value from the last document for each group. Order
-          is only defined if the documents are in a defined order.
+          is only defined if the documents are sorted.
           
           Distinct from the :expression:`$last` array operator.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
       * - :group:`$max`
 
         - Returns the highest expression value for each group.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
       * - :expression:`$mergeObjects`
 
         - Returns a document created by combining the input documents
@@ -982,32 +1010,52 @@ content: |
 
         - Returns the lowest expression value for each group.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
       * - :group:`$push`
 
-        - Returns an array of expression values for each group.
+        - Returns an array of expression values for documents in each
+          group.
+
+          .. versionchanged:: 5.0
 
+             Available in :pipeline:`$setWindowFields` stage.
 
       * - :group:`$stdDevPop`
 
         - Returns the population standard deviation of the input values.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
       * - :group:`$stdDevSamp`
 
         - Returns the sample standard deviation of the input values.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
       * - :group:`$sum`
 
         - Returns a sum of numerical values. Ignores non-numeric values.
 
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
 
 ---
 ref: agg-operators-accumulators-project
 content: |
 
-   .. versionchanged:: 3.2
+   .. versionchanged:: 5.0
 
    The following accumulator operators are also available in the
-   :pipeline:`$project`, :pipeline:`$addFields`, and :pipeline:`$set` stages.
+   :pipeline:`$project`, :pipeline:`$addFields`, :pipeline:`$set`, and,
+   starting in MongoDB 5.0, the :pipeline:`$setWindowFields` stages.
 
    .. list-table::
       :header-rows: 1
@@ -1021,7 +1069,6 @@ content: |
         - Returns an average of the specified expression or list of
           expressions for each document. Ignores non-numeric values.
 
-
       * - :group:`$max`
 
         - Returns the maximum of the specified expression or list of
@@ -1044,4 +1091,200 @@ content: |
 
         - Returns a sum of numerical values. Ignores non-numeric values.
 
+---
+ref: agg-operators-window
+content: |
+
+   .. versionadded:: 5.0
+
+   Window operators return values from a defined span of documents from
+   a collection, known as a *window*. A :ref:`window
+   <setWindowFields-window>` is defined in the
+   :pipeline:`$setWindowFields` stage, available starting in MongoDB
+   5.0.
+
+   The following window operators are available in the
+   :pipeline:`$setWindowFields` stage.
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 80
+
+      * - Name
+        - Description
+
+      * - :group:`$addToSet`
+
+        - Returns an array of all unique values that results from
+          applying an :ref:`expression <aggregation-expressions>` to
+          each document.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$avg`
+
+        - Returns the average for the specified :ref:`expression
+          <aggregation-expressions>`. Ignores non-numeric values.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$count`
+
+        - Returns the number of documents in the group or window.
+
+          Distinct from the :pipeline:`$count` pipeline stage.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$covariancePop`
+
+        - Returns the population covariance of two numeric
+          :ref:`expressions <aggregation-expressions>`.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$covarianceSamp`
+
+        - Returns the sample covariance of two numeric
+          :ref:`expressions <aggregation-expressions>`.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$denseRank`
+
+        - Returns the document position (known as the rank) relative to
+          other documents in the :pipeline:`$setWindowFields` stage
+          :ref:`partition <setWindowFields-partitionBy>`. There are no
+          gaps in the ranks. Ties receive the same rank.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$derivative`
+
+        - Returns the mathematical derivative of the numeric
+          :ref:`expression <aggregation-expressions>`. 
+
+          .. versionadded:: 5.0
+
+      * - :group:`$documentNumber`
+
+        - Returns the position of a document (known as the document
+          number) in the :pipeline:`$setWindowFields` stage
+          :ref:`partition <setWindowFields-partitionBy>`. Ties result in
+          different adjacent document numbers.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$expMovingAvg`
+
+        - Returns the exponential moving average for the numeric
+          :ref:`expression <aggregation-expressions>`.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$first`
+
+        - Returns the value that results from applying an
+          :ref:`expression <aggregation-expressions>` to the first
+          document in a group or :ref:`window <setWindowFields-window>`.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$integral`
+
+        - Returns the mathematical integral of the numeric
+          :ref:`expression <aggregation-expressions>`.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$last`
+
+        - Returns the value that results from applying an
+          :ref:`expression <aggregation-expressions>` to the last
+          document in a group or :ref:`window <setWindowFields-window>`.
+        
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$max`
+
+        - Returns the maximum value that results from applying an
+          :ref:`expression <aggregation-expressions>` to each document.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$min`
+
+        - Returns the minimum value that results from applying an
+          :ref:`expression <aggregation-expressions>` to each document.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$push`
+
+        - Returns an array of values that result from applying an
+          :ref:`expression <aggregation-expressions>` to each document.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$rank`
+
+        - Returns the document position (known as the rank) relative to
+          other documents in the :pipeline:`$setWindowFields` stage
+          :ref:`partition <setWindowFields-partitionBy>`.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$shift`
+
+        - Returns the value from an :ref:`expression
+          <aggregation-expressions>` applied to a document in a
+          specified position relative to the current document in the
+          :pipeline:`$setWindowFields` stage :ref:`partition
+          <setWindowFields-partitionBy>`.
+
+          .. versionadded:: 5.0
+
+      * - :group:`$stdDevPop`
+
+        - Returns the population standard deviation that results from
+          applying a numeric :ref:`expression <aggregation-expressions>`
+          to each document.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$stdDevSamp`
+
+        - Returns the sample standard deviation that results from
+          applying a numeric :ref:`expression <aggregation-expressions>`
+          to each document.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
+      * - :group:`$sum`
+
+        - Returns the sum that results from applying a numeric
+          :ref:`expression <aggregation-expressions>` to each document.
+
+          .. versionchanged:: 5.0
+
+             Available in :pipeline:`$setWindowFields` stage.
+
 ...