Database Manual / Reference / Query Language / Aggregation Stages

$setWindowFields (aggregation stage)（聚合阶段）

Definition定义

$setWindowFields

New in version 5.0.在版本5.0中新增。5.0版本中的新功能。

Performs operations on a specified span of documents in a collection, known as a window, and returns the results based on the chosen window operator.对集合（称为窗口）中指定范围的文档执行操作，并根据所选的窗口运算符返回结果。

For example, you can use the $setWindowFields stage to output the:例如，您可以使用$setWindowFields阶段输出：

  • Difference in sales between two documents in a collection.收款中两份单据之间的销售额差异。
  • Sales rankings.销售排名。
  • Cumulative sales totals.累计销售总额。
  • Analysis of complex time series information without exporting the data to an external database.分析复杂的时间序列信息，而无需将数据导出到外部数据库。

Syntax语法

The $setWindowFields stage syntax:$setWindowFields阶段语法：

{
   $setWindowFields: {
      partitionBy: <expression>,
      sortBy: {
         <sort field 1>: <sort order>,
         <sort field 2>: <sort order>,
         ...,
         <sort field n>: <sort order>
      },
      output: {
         <output field 1>: {
            <window operator>: <window operator parameters>,
            window: {
               documents: [ <lower boundary>, <upper boundary> ],
               range: [ <lower boundary>, <upper boundary> ],
               unit: <time unit>
            }
         },
         <output field 2>: { ... },
         ...
         <output field n>: { ... }
      }
   }
}

The $setWindowFields stage takes a document with these fields:$setWindowFields阶段接收具有以下字段的文档：

Field字段Necessity必要性Description描述
partitionByOptional可选

Specifies an expression to group the documents. 指定用于对文档进行分组的表达式。In the $setWindowFields stage, the group of documents is known as a partition. Default is one partition for the entire collection.在$setWindowFields阶段，文档组被称为分区。默认情况下，整个集合只有一个分区。

sortByRequired for some operators (see Restrictions)某些运算符需要（请参阅限制）

Specifies the field(s) to sort the documents by in the partition. Uses the same syntax as the $sort stage. Default is no sorting.指定分区中用于对文档进行排序的字段。使用与$sort阶段相同的语法。默认值为无排序。

outputRequired必需

Specifies the field(s) to append to the documents in the output returned by the $setWindowFields stage. 指定要附加到$setWindowFields阶段返回的输出中的文档的字段。Each field is set to the result returned by the window operator.每个字段都设置为窗口运算符返回的结果。

A field can contain dots to specify embedded document fields and array fields. 字段可以包含点，以指定嵌入式文档字段和数组字段。The semantics for the embedded document dotted notation in the $setWindowFields stage are the same as the $addFields and $set stages. $setWindowFields阶段中嵌入式文档点符号的语义与$addFields和$set阶段相同。See embedded document $addFields example and embedded document $set example.请参阅嵌入式文档$addFields示例和嵌入式文档$set示例。

windowOptional可选

Specifies the window boundaries and parameters. Window boundaries are inclusive. Default is an unbounded window, which includes all documents in the partition.指定窗口边界和参数。窗口边界是包容性的。默认是一个无边界窗口，其中包括分区中的所有文档。

Specify either a documents or range window.指定documents或范围窗口。

documentsOptional可选

A window where the lower and upper boundaries are specified relative to the position of the current document read from the collection.一个窗口，其中相对于从集合中读取的当前文档的位置指定了下限和上限。

The window boundaries are specified using a two element array containing a lower and upper limit string or integer. Use:使用包含下限和上限字符串或整数的两元素数组指定窗口边界。用途：

  • The "current" string for the current document position in the output.输出中当前文档位置的"current"字符串。
  • The "unbounded" string for the first or last document position in the partition.分区中第一个或最后一个文档位置的"unbounded"字符串。
  • An integer for a position relative to the current document. Use a negative integer for a position before the current document. Use a positive integer for a position after the current document. 相对于当前文档的位置的整数。在当前文档之前的位置使用负整数。在当前文档之后的位置使用正整数。0 is the current document position.0是当前文档位置。

See Documents Window Examples.请参阅文档窗口示例。

rangeOptional可选

A window where the lower and upper boundaries are defined using a range of values based on the sortBy field in the current document.一个窗口，其中使用基于当前文档中sortBy字段的一系列值来定义下限和上限。

The window boundaries are specified using a two element array containing a lower and upper limit string or number. Use:使用包含下限和上限字符串或数字的两元素数组指定窗口边界。用途：

  • The "current" string for the current document position in the output.输出中当前文档位置的"current"字符串。
  • The "unbounded" string for the first or last document position in the partition.分区中第一个或最后一个文档位置的"unbounded"字符串。
  • A number to add to the value of the sortBy field for the current document. 要添加到当前文档的sortBy字段值的数字。A document is in the window if the sortBy field value is inclusively within the lower and upper boundaries.如果sortBy字段值包含在下限和上限内，则文档在窗口中。

See Range Window Example.请参见范围窗口示例。

unitOptional可选

Specifies the units for time range window boundaries. Can be set to one of these strings:指定时间范围窗口边界的单位。可以设置为以下字符串之一：

  • "year"
  • "quarter"
  • "month"
  • "week"
  • "day"
  • "hour"
  • "minute"
  • "second"
  • "millisecond"

If omitted, default numeric range window boundaries are used.如果省略，则使用默认的数值范围窗口边界。

See Time Range Window Examples.请参阅时间范围窗口示例。

Tip

Examples例子

Behavior行为

The $setWindowFields stage appends new fields to existing documents. You can include one or more $setWindowFields stages in an aggregation operation.$setWindowFields阶段将新字段附加到现有文档中。您可以在聚合操作中包含一个或多个$setWindowFields阶段。

Starting in MongoDB 5.3, you can use the $setWindowFields stage with transactions and the "snapshot" read concern.从MongoDB 5.3开始，您可以将$setWindowFields阶段与事务和"snapshot"读取关注一起使用。

The $setWindowFields stage doesn't guarantee the order of the returned documents.$setWindowFields阶段不保证返回文档的顺序。

Window Operators窗口运算符

These operators can be used with the $setWindowFields stage:这些运算符可以与$setWindowFields阶段一起使用：

Restrictions限制

Restrictions for the $setWindowFields stage:$setWindowFields阶段的限制：

  • Prior to MongoDB 5.3, the $setWindowFields stage cannot be used:在MongoDB 5.3之前，不能使用$setWindowFields阶段：
  • sortBy is required for:以下情况需要sortBy：
  • Range windows require all sortBy values to be numbers.范围窗口要求所有sortBy值都是数字。
  • Time range时间范围 windows require all sortBy values to be dates.窗口要求所有sortBy值都是日期。
  • Range范围 and 和time range时间范围 windows can only contain one sortBy field and the sort must be ascending.窗口只能包含一个sortBy字段，排序必须是升序。
  • You cannot specify both a documents window and a range window.您不能同时指定documents窗口和范围窗口。
  • These operators use an implicit window and return an error if you specify a window option:这些运算符使用隐式窗口，如果指定window选项，则返回错误：
  • For range windows, only numbers in the specified range are included in the window. Missing, undefined, and null values are excluded.对于范围窗口，窗口中只包含指定范围内的数字。缺失、未定义和null值被排除在外。
  • For time range windows:对于时间范围窗口：
    • Only date and time types are included in the window.窗口中仅包含日期和时间类型。
    • Numeric boundary values must be integers. For example, you can use 2 hours as a boundary but you cannot use 1.5 hours.数值边界值必须是整数。例如，您可以使用2小时作为边界，但不能使用1.5小时。
  • For empty windows or windows with incompatible values (for example, using $sum on strings), the returned value depends on the operator:对于空窗口或具有不兼容值的窗口（例如，在字符串上使用$sum），返回值取决于运算符：
    • For $count and $sum, the returned value is 0.对于$count和$sum，返回值为0。
    • For $addToSet and $push, the returned value is an empty array.对于$addToSet和$push，返回的值是一个空数组。
    • For all other operators, the returned value is null.对于所有其他运算符，返回值为null。

Examples示例

MongoDB Shell

Create a cakeSales collection that contains cake sales in the states of California (CA) and Washington (WA):创建一个cakeSales集合，其中包含加利福尼亚州（CA）和华盛顿州（WA）的蛋糕销售：

db.cakeSales.insertMany( [
   { _id: 0, type: "chocolate", orderDate: new Date("2020-05-18T14:10:30Z"),
     state: "CA", price: 13, quantity: 120 },
   { _id: 1, type: "chocolate", orderDate: new Date("2021-03-20T11:30:05Z"),
     state: "WA", price: 14, quantity: 140 },
   { _id: 2, type: "vanilla", orderDate: new Date("2021-01-11T06:31:15Z"),
     state: "CA", price: 12, quantity: 145 },
   { _id: 3, type: "vanilla", orderDate: new Date("2020-02-08T13:13:23Z"),
     state: "WA", price: 13, quantity: 104 },
   { _id: 4, type: "strawberry", orderDate: new Date("2019-05-18T16:09:01Z"),
     state: "CA", price: 41, quantity: 162 },
   { _id: 5, type: "strawberry", orderDate: new Date("2019-01-08T06:12:03Z"),
     state: "WA", price: 43, quantity: 134 }
] )

The following examples use the cakeSales collection.以下示例使用cakeSales集合。

Documents Window Examples文档窗口示例

Use Documents Window to Obtain Cumulative Quantity for Each State使用文档窗口获取每个州的累计数量

This example uses a documents window in $setWindowFields to output the cumulative cake sales quantity for each state:此示例使用$setWindowFields中的documents窗口输出每个state（州）的累计蛋糕销售quantity（数量）：

db.cakeSales.aggregate( [
   {
      $setWindowFields: {
         partitionBy: "$state",
         sortBy: { orderDate: 1 },
         output: {
            cumulativeQuantityForState: {
               $sum: "$quantity",
               window: {
                  documents: [ "unbounded", "current" ]
               }
            }
         }
      }
   }
] )

In the example:在示例中：

  • partitionBy: "$state" partitions the documents in the collection by state. There are partitions for CA and WA.按state（州）对集合中的文档进行分区。CA和WA有分区。
  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1), so the earliest orderDate is first.按orderDate升序（1）对每个分区中的文档进行排序，因此最早的orderDate位居前列。
  • output:
    • Sets the cumulativeQuantityForState field to the cumulative quantity for each state, which increases by successive additions to the previous value in the partition.将cumulativeQuantityForState字段设置为每个state的累积数量，该quantity通过连续添加到分区中的前一个值而增加。
    • Calculates the cumulative quantity using the $sum operator run in a documents window.使用在documents窗口中运行的$sum运算符计算累计quantity。
      The window contains documents between an unbounded lower limit and the current document. 该window包含介于unbounded下限和current文档之间的文档。This means $sum returns the cumulative quantity for the documents between the beginning of the partition and the current document.这意味着$sum返回从分区开始到当前文档之间的文档的累积quantity。

In this example output, the cumulative quantity for CA and WA is shown in the cumulativeQuantityForState field:在此示例输出中，CA和WA的累积quantity显示在accumulateQuantityForState字段中：

{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
  "state" : "CA", "price" : 41, "quantity" : 162, "cumulativeQuantityForState" : 162 }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
  "state" : "CA", "price" : 13, "quantity" : 120, "cumulativeQuantityForState" : 282 }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
  "state" : "CA", "price" : 12, "quantity" : 145, "cumulativeQuantityForState" : 427 }
{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
  "state" : "WA", "price" : 43, "quantity" : 134, "cumulativeQuantityForState" : 134 }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
  "state" : "WA", "price" : 13, "quantity" : 104, "cumulativeQuantityForState" : 238 }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
  "state" : "WA", "price" : 14, "quantity" : 140, "cumulativeQuantityForState" : 378 }

Use Documents Window to Obtain Cumulative Quantity for Each Year使用文档窗口获取每年的累计数量

This example uses a documents window in $setWindowFields to output the cumulative cake sales quantity for each $year in orderDate:此示例使用$setWindowFields中的documents窗口输出orderDate中每个$year的累计蛋糕销售quantity：

db.cakeSales.aggregate( [
   {
      $setWindowFields: {
         partitionBy: { $year: "$orderDate" },
         sortBy: { orderDate: 1 },
         output: {
            cumulativeQuantityForYear: {
               $sum: "$quantity",
               window: {
                  documents: [ "unbounded", "current" ]
               }
            }
         }
      }
   }
] )

In the example:在示例中：

  • partitionBy: { $year: "$orderDate" } partitions the documents in the collection by $year in orderDate. There are are partitions for 2019, 2020, and 2021.按$year按orderDate对集合中的文档进行分区。2019年、2020年和2021年有分区。
  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1), so the earliest orderDate is first.按orderDate升序（1）对每个分区中的文档进行排序，因此最早的orderDate位居前列。
  • output:
    • Sets the cumulativeQuantityForYear field to the cumulative quantity for each year, which increases by successive additions to the previous value in the partition.将cumulativeQuantityForYear字段设置为每年的累积quantity，该数量通过连续添加到分区中的上一个值而增加。
    • Calculates the cumulative quantity using the $sum operator run in a documents window.使用在documents窗口中运行的$sum运算符计算累计quantity。
      The window contains documents between an unbounded lower limit and the current document. This means $sum returns the cumulative quantity for the documents between the beginning of the partition and the current document.该window包含介于unbounded下限和current文档之间的文档。这意味着$sum返回从分区开始到当前文档之间的文档的累积quantity。

In this example output, the cumulative quantity for each year is shown in the cumulativeQuantityForYear field:在此示例输出中，每年的累积quantity显示在cumulativeQuantityForYear字段中：

{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
  "state" : "WA", "price" : 43, "quantity" : 134, "cumulativeQuantityForYear" : 134 }
{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
  "state" : "CA", "price" : 41, "quantity" : 162, "cumulativeQuantityForYear" : 296 }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
  "state" : "WA", "price" : 13, "quantity" : 104, "cumulativeQuantityForYear" : 104 }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
  "state" : "CA", "price" : 13, "quantity" : 120, "cumulativeQuantityForYear" : 224 }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
  "state" : "CA", "price" : 12, "quantity" : 145, "cumulativeQuantityForYear" : 145 }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
  "state" : "WA", "price" : 14, "quantity" : 140, "cumulativeQuantityForYear" : 285 }

Use Documents Window to Obtain Moving Average Quantity for Each Year使用文档窗口获取每年的移动平均数量

This example uses a documents window in $setWindowFields to output the moving average for the cake sales quantity:此示例使用$setWindowFields中的documents窗口输出蛋糕销售quantity的移动平均值：

db.cakeSales.aggregate( [
   {
      $setWindowFields: {
         partitionBy: { $year: "$orderDate" },
         sortBy: { orderDate: 1 },
         output: {
            averageQuantity: {
               $avg: "$quantity",
               window: {
                  documents: [ -1, 0 ]
               }
            }
         }
      }
   }
] )

In the example:在示例中：

  • partitionBy: "$orderDate" partitions the documents in the collection by $year in orderDate. There are are partitions for 2019, 2020, and 2021.按$year按orderDate对集合中的文档进行分区。2019年、2020年和2021年有分区。
  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1), so the earliest orderDate is first.按orderDate升序（1）对每个分区中的文档进行排序，因此最早的orderDate位居前列。
  • output:
    • Sets the averageQuantity field to the moving average quantity for each year.将averageQuantity字段设置为每年的移动平均quantity。
    • Calculates the moving average quantity using the $avg operator run in a documents window.使用在documents窗口中运行的$avg运算符计算移动平均quantity。
      The window contains documents between -1 and 0. window包含介于-1和0之间的文档。This means $avg returns the moving average quantity between the document before the current document (-1) and the current document (0) in the partition.这意味着$avg返回分区中当前文档之前的文档（-1）和当前文档（0）之间的移动平均quantity。

In this example output, the moving average quantity is shown in the averageQuantity field:在此示例输出中，移动平均quantity显示在averageQuantity字段中：

{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
  "state" : "WA", "price" : 43, "quantity" : 134, "averageQuantity" : 134 }
{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
  "state" : "CA", "price" : 41, "quantity" : 162, "averageQuantity" : 148 }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
  "state" : "WA", "price" : 13, "quantity" : 104, "averageQuantity" : 104 }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
  "state" : "CA", "price" : 13, "quantity" : 120, "averageQuantity" : 112 }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
  "state" : "CA", "price" : 12, "quantity" : 145, "averageQuantity" : 145 }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
  "state" : "WA", "price" : 14, "quantity" : 140, "averageQuantity" : 142.5 }

Use Documents Window to Obtain Cumulative and Maximum Quantity for Each Year使用文档窗口获取每年的累计和最大数量

This example uses a documents window in $setWindowFields to output the cumulative and maximum cake sales quantity values for each $year in orderDate:此示例使用$setWindowFields中的documents窗口输出orderDate中每个$year的累计和最大蛋糕销售quantity值：

db.cakeSales.aggregate( [
   {
      $setWindowFields: {
         partitionBy: { $year: "$orderDate" },
         sortBy: { orderDate: 1 },
         output: {
            cumulativeQuantityForYear: {
               $sum: "$quantity",
               window: {
                  documents: [ "unbounded", "current" ]
               }
            },
            maximumQuantityForYear: {
               $max: "$quantity",
               window: {
                  documents: [ "unbounded", "unbounded" ]
               }
            }
         }
      }
   }
] )

In the example:在示例中：

  • partitionBy: "$orderDate" partitions the documents in the collection by $year in orderDate. There are are partitions for 2019, 2020, and 2021.按$year按orderDate对集合中的文档进行分区。2019年、2020年和2021年有分区。
  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1), so the earliest orderDate is first.按orderDate升序（1）对每个分区中的文档进行排序，因此最早的orderDate位居前列。
  • output:
    • Sets the cumulativeQuantityForYear field to the cumulative quantity for each year.将cumulativeQuantityForYear字段设置为每年的累积quantity。

    • Calculates the cumulative quantity using the $sum operator run in a documents window.使用在documents窗口中运行的$sum运算符计算累计quantity。

      The window contains documents between an unbounded lower limit and the current document. 该window包含介于unbounded下限和current文档之间的文档。This means $sum returns the cumulative quantity for the documents between the beginning of the partition and the current document.这意味着$sum返回从分区开始到当前文档之间的文档的累积数量。

    • Sets the maximumQuantityForYear field to the maximum quantity for each year.将maximumQuantityForYear字段设置为每年的最大quantity。
    • Calculates the maximum quantity of all the documents using the $max operator run in a documents window.使用在documents窗口中运行的$max运算符计算所有文档的最大quantity。
      The window contains documents between an unbounded lower and upper limit. 该window包含在unbounded下限和unbounded上限之间的文档。This means $max returns the maximum quantity for the documents in the partition.这意味着$max返回分区中文档的最大数量。

In this example output, the cumulative quantity is shown in the cumulativeQuantityForYear field and the maximum quantity is shown in the maximumQuantityForYear field:在此示例输出中，累积quantity显示在cumulativeQuantityForYear字段中，最大quantity显示在maximumQuantityForYear字段中：

{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
  "state" : "WA", "price" : 43, "quantity" : 134,
  "cumulativeQuantityForYear" : 134, "maximumQuantityForYear" : 162 }
{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
  "state" : "CA", "price" : 41, "quantity" : 162,
  "cumulativeQuantityForYear" : 296, "maximumQuantityForYear" : 162 }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
  "state" : "WA", "price" : 13, "quantity" : 104,
  "cumulativeQuantityForYear" : 104, "maximumQuantityForYear" : 120 }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
  "state" : "CA", "price" : 13, "quantity" : 120,
   "cumulativeQuantityForYear" : 224, "maximumQuantityForYear" : 120 }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
  "state" : "CA", "price" : 12, "quantity" : 145,
  "cumulativeQuantityForYear" : 145, "maximumQuantityForYear" : 145 }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
  "state" : "WA", "price" : 14, "quantity" : 140,
  "cumulativeQuantityForYear" : 285, "maximumQuantityForYear" : 145 }

Range Window Example范围窗口示例

This example uses a range window in $setWindowFields to return the sum of the quantity values of cakes sold for orders within plus or minus 10 dollars of the current document's price value:此示例使用$setWindowFields中的一个range窗口返回当前文档价格值正负10美元范围内的订单所售蛋糕数量值的总和：

db.cakeSales.aggregate( [
   {
      $setWindowFields: {
         partitionBy: "$state",
         sortBy: { price: 1 },
         output: {
            quantityFromSimilarOrders: {
               $sum: "$quantity",
               window: {
                  range: [ -10, 10 ]
               }
            }
         }
      }
   }
] )

In the example:在示例中：

  • partitionBy: "$state" partitions the documents in the collection by state. There are partitions for CA and WA.按state对集合中的文档进行分区。CA和WA有分区。
  • sortBy: { price: 1 } sorts the documents in each partition by price in ascending order (1), so the lowest price is first.按price升序（1）对每个分区中的文档进行排序，因此最低price位居前列。
  • output sets the quantityFromSimilarOrders field to the sum of the quantity values from the documents in a range window.将quantityFromSimilarOrders字段设置为range窗口中文档的quantity值之和。
    • The window contains documents between a lower limit of -10 and an upper limit of 10. The range is inclusive.该window包含下限-10和上限10之间的文档。范围是包含性的。
    • $sum returns the sum of quantity values contained in a range of plus or minus 10 dollars of the current document's price value.返回当前文档price值正负10美元范围内包含的quantity值的总和。

In this example output, the sum of the quantity values for documents in the window is shown in the quantityFromSimilarOrders field:在此示例输出中，窗口中文档的quantity值之和显示在quantityFromSimilarOrders字段中：

{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
  "state" : "CA", "price" : 12, "quantity" : 145, "quantityFromSimilarOrders" : 265 }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
  "state" : "CA", "price" : 13, "quantity" : 120, "quantityFromSimilarOrders" : 265 }
{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
  "state" : "CA", "price" : 41, "quantity" : 162, "quantityFromSimilarOrders" : 162 }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
  "state" : "WA", "price" : 13, "quantity" : 104, "quantityFromSimilarOrders" : 244 }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
  "state" : "WA", "price" : 14, "quantity" : 140, "quantityFromSimilarOrders" : 244 }
{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
  "state" : "WA", "price" : 43, "quantity" : 134, "quantityFromSimilarOrders" : 134 }

Time Range Window Examples时间范围窗口示例

Use a Time Range Window with a Positive Upper Bound使用具有正上限的时间范围窗口

The following example uses a window with a positive upper bound time range unit in $setWindowFields. The pipeline outputs an array of orderDate values for each state that match the specified time range.以下示例使用$setWindowFields中具有正上限时间范围单位的window。管道输出与指定时间范围匹配的每个state的orderDate值数组。

db.cakeSales.aggregate( [
   {
      $setWindowFields: {
         partitionBy: "$state",
         sortBy: { orderDate: 1 },
         output: {
            recentOrders: {
               $push: "$orderDate",
               window: {
                  range: [ "unbounded", 10 ],
                  unit: "month"
               }
            }
         }
      }
   }
] )

In the example:在示例中：

  • partitionBy: "$state" partitions the documents in the collection by state. There are partitions for CA and WA.按state对集合中的文档进行分区。CA和WA有分区。
  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1), so the earliest orderDate is first.按orderDate升序（1）对每个分区中的文档进行排序，因此最早的orderDate位居前列。
  • output:
    • Sets the recentOrders field to an array of orderDate values for the documents in each state. The array elements are expanded with additions to the previous elements in the array.将recentOrders字段设置为每个state的文档的orderDate值数组。数组元素通过添加数组中的前一个元素进行扩展。
    • Uses $push to return an array of orderDate values from the documents in a range window.使用$push从范围窗口中的文档返回orderDate值数组。
  • The window contains documents between an unbounded lower limit and an upper limit set to 10 (10 months after the current document's orderDate value) using a time range unit.该window包含使用时间范围单位设置为10（当前文档的orderDate值后10个月）的无限下限和上限之间的文档。
  • $push returns the array of orderDate values for the documents between the beginning of the partition and the documents with orderDate values inclusively in a range of the current document's orderDate value plus 10 months.$push返回分区开始和orderDate值在当前文档orderDate值加10个月范围内的文档之间的orderDate值数组。

In this example output, the array of orderDate values for CA and WA is shown in the recentOrders field:在这个示例输出中，CA和WA的orderDate值数组显示在recentOrders字段中：

{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
  "state" : "CA", "price" : 41, "quantity" : 162,
  "recentOrders" : [ ISODate("2019-05-18T16:09:01Z") ] }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
  "state" : "CA", "price" : 13, "quantity" : 120,
  "recentOrders" : [ ISODate("2019-05-18T16:09:01Z"), ISODate("2020-05-18T14:10:30Z"), ISODate("2021-01-11T06:31:15Z") ] }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
  "state" : "CA", "price" : 12, "quantity" : 145,
  "recentOrders" : [ ISODate("2019-05-18T16:09:01Z"), ISODate("2020-05-18T14:10:30Z"), ISODate("2021-01-11T06:31:15Z") ] }
{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
  "state" : "WA", "price" : 43, "quantity" : 134,
  "recentOrders" : [ ISODate("2019-01-08T06:12:03Z") ] }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
  "state" : "WA", "price" : 13, "quantity" : 104,
  "recentOrders" : [ ISODate("2019-01-08T06:12:03Z"), ISODate("2020-02-08T13:13:23Z") ] }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
  "state" : "WA", "price" : 14, "quantity" : 140,
  "recentOrders" : [ ISODate("2019-01-08T06:12:03Z"), ISODate("2020-02-08T13:13:23Z"), ISODate("2021-03-20T11:30:05Z") ] }

Use a Time Range Window with a Negative Upper Bound使用具有负上限的时间范围窗口

The following example uses a window with a negative upper bound time range unit in $setWindowFields. 以下示例使用$setWindowFields中具有负上限时间范围unit的window。The pipeline outputs an array of orderDate values for each state that match the specified time range.管道输出与指定时间范围匹配的每个state的orderDate值数组。

db.cakeSales.aggregate( [
   {
      $setWindowFields: {
         partitionBy: "$state",
         sortBy: { orderDate: 1 },
         output: {
            recentOrders: {
               $push: "$orderDate",
               window: {
                  range: [ "unbounded", -10 ],
                  unit: "month"
               }
            }
         }
      }
   }
] )

In the example:在示例中：

  • partitionBy: "$state" partitions the documents in the collection by state. There are partitions for CA and WA.按state对集合中的文档进行分区。CA和WA有分区。
  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1), so the earliest orderDate is first.按orderDate升序（1）对每个分区中的文档进行排序，因此最早的orderDate是第一个。
  • output:
    • Sets the recentOrders field to an array of orderDate values for the documents in each state. The array elements are expanded with additions to the previous elements in the array.将recentOrders字段设置为每个state的文档的orderDate值数组。数组元素通过添加数组中的前一个元素进行扩展。
    • Uses $push to return an array of orderDate values from the documents in a range window.使用$push从range窗口中的文档返回orderDate值数组。
  • The window contains documents between an unbounded lower limit and an upper limit set to -10 (10 months before the current document's orderDate value) using a time range unit.该window包含使用时间范围单位设置为-10（当前文档orderDate值前10个月）的unbounded下限和unbounded上限之间的文档。
  • $push returns the array of orderDate values for the documents between the beginning of the partition and the documents with orderDate values inclusively in a range of the current document's orderDate value minus 10 months.$push返回分区开始和orderDate值在当前文档orderDate值减去10个月范围内的文档之间的orderDate值数组。

In this example output, the array of orderDate values for CA and WA is shown in the recentOrders field:在这个示例输出中，CA和WA的orderDate值数组显示在recentOrders字段中：

{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
  "state" : "CA", "price" : 41, "quantity" : 162,
  "recentOrders" : [ ] }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
  "state" : "CA", "price" : 13, "quantity" : 120,
  "recentOrders" : [ ISODate("2019-05-18T16:09:01Z") ] }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
  "state" : "CA", "price" : 12, "quantity" : 145,
  "recentOrders" : [ ISODate("2019-05-18T16:09:01Z") ] }
{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
  "state" : "WA", "price" : 43, "quantity" : 134,
  "recentOrders" : [ ] }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
  "state" : "WA", "price" : 13, "quantity" : 104,
  "recentOrders" : [ ISODate("2019-01-08T06:12:03Z") ] }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
  "state" : "WA", "price" : 14, "quantity" : 140,
  "recentOrders" : [ ISODate("2019-01-08T06:12:03Z"), ISODate("2020-02-08T13:13:23Z") ] }

Comparison with Previous Values Example与先前值的比较示例

The following example uses $setWindowFields with the $shift operator and the $set stage to compare fields in a collection.以下示例使用$setWindowFields、$shift运算符和$set阶段来比较集合中的字段。

db.cakeSales.aggregate( [
  {
    $setWindowFields: {
      partitionBy: "$type",
      sortBy: { orderDate: 1 },
      output: {
        previousPrice: {
          $shift: {
            output: "$price",
            by: -1
          }
        }
      }
    }
  },
  {
    $set: {
      priceComparison: {
        $cond: [
          { $eq: ["$price", "$previousPrice"] },
          "same",
          {
            $cond: [
              { $gt: ["$price", "$previousPrice"] },
              "higher",
              "lower"
            ]
          }
        ]
      }
    }
  },
] )

In the example:在示例中：

  • partitionBy: "$type" partitions the documents in the collection by type so each type's calculations are kept separate.按type对集合中的文档进行分区，这样每种类型的计算都是分开的。
  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1).按orderDate升序（1）对每个分区中的文档进行排序。
  • output.previousPrice uses the $shift operator to capture the price from the immediately preceding order within the same year.使用$shift运算符捕获同一年内前一个订单的price。
  • $set adds a new field called priceComparison, and sets that field's value to higher, lower, or same based on the comparison to previousPrice.添加一个名为priceComparison的新字段，并根据与先前价格的比较将该字段的值设置为higher、lower或same。

In this example output, the comparison result is shown in the priceComparison field:在这个示例输出中，比较结果显示在priceComparison字段中：

[
  {
    _id: 0,
    type: 'chocolate',
    orderDate: ISODate('2020-05-18T14:10:30.000Z'),
    state: 'CA',
    price: 13,
    quantity: 120,
    previousPrice: null,
    priceComparison: 'higher'
  },
  {
    _id: 1,
    type: 'chocolate',
    orderDate: ISODate('2021-03-20T11:30:05.000Z'),
    state: 'WA',
    price: 14,
    quantity: 140,
    previousPrice: 13,
    priceComparison: 'higher'
  },
  {
    _id: 5,
    type: 'strawberry',
    orderDate: ISODate('2019-01-08T06:12:03.000Z'),
    state: 'WA',
    price: 43,
    quantity: 134,
    previousPrice: null,
    priceComparison: 'higher'
  },
  {
    _id: 4,
    type: 'strawberry',
    orderDate: ISODate('2019-05-18T16:09:01.000Z'),
    state: 'CA',
    price: 41,
    quantity: 162,
    previousPrice: 43,
    priceComparison: 'lower'
  },
  {
    _id: 3,
    type: 'vanilla',
    orderDate: ISODate('2020-02-08T13:13:23.000Z'),
    state: 'WA',
    price: 13,
    quantity: 104,
    previousPrice: null,
    priceComparison: 'higher'
  },
  {
    _id: 2,
    type: 'vanilla',
    orderDate: ISODate('2021-01-11T06:31:15.000Z'),
    state: 'CA',
    price: 12,
    quantity: 145,
    previousPrice: 13,
    priceComparison: 'lower'
  }
]
C#

The following WeatherMeasurement class represents documents in a collection of weather measurements:以下WeatherMeasurement类表示天气测量集合中的文档：

public class WeatherMeasurement
{
    public Guid Id { get; set; }
    
    public string LocalityId { get; set; }
    
    public DateTime MeasurementDateTime { get; set; }
  
    public float Rainfall { get; set; }
    
    public float Temperature { get; set; }
}

To use the MongoDB .NET/C# driver to add a $setWindowFields stage to an aggregation pipeline, call the SetWindowFields() method on a PipelineDefinition object.要使用MongoDB .NET/C#驱动程序将$setWindowFields阶段添加到聚合管道中，请在PipelineDefinition对象上调用SetWindowFields()方法。

The following example creates a pipeline stage that uses the Rainfall and Temperature fields to compute the accumulated rainfall and a moving average temperature over the past month for each locality:以下示例创建了一个管道阶段，该阶段使用Rainfall（降雨）和Temperature（温度）字段计算每个地点过去一个月的累积降雨量和移动平均温度：

var pipeline = new EmptyPipelineDefinition<WeatherMeasurement>()
    .SetWindowFields(
        partitionBy: w => w.LocalityId,
        sortBy: Builders<WeatherMeasurement>.Sort.Ascending(
            w => w.MeasurementDateTime),
        output: o => new
        {
            MonthlyRainfall = o.Sum(
                w => w.Rainfall, RangeWindow.Create(
                    RangeWindow.Months(-1),
                    RangeWindow.Current)
            ),
            TemperatureAvg = o.Average(
                w => w.Temperature, RangeWindow.Create(
                    RangeWindow.Months(-1),
                    RangeWindow.Current)
            )
        }
    );
Node.js

The Node.js examples on this page use the sample_weatherdata.data collection from the Atlas sample datasets. 此页面上的Node.js示例使用Atlas示例数据集中的sample_weatherdata.data集合。To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Get Started in the MongoDB Node.js driver documentation.要了解如何创建免费的MongoDB Atlas集群并加载示例数据集，请参阅MongoDB Node.js驱动程序文档中的入门。

To use the MongoDB Node.js driver to add a $setWindowFields stage to an aggregation pipeline, use the $setWindowFields operator in a pipeline object.要使用MongoDB Node.js驱动程序将$setWindowFields阶段添加到聚合管道中，请在管道对象中使用$setWindowFields运算符。

The following example creates a pipeline stage that calculates the average airTemperature.value and the total waveMeasurement.waves.height for each unique value of callLetters over the past month. The example then runs the aggregation pipeline:以下示例创建了一个管道阶段，该阶段计算过去一个月callLetters的每个唯一值的平均airTemperature.value（空气温度值）和总waveMeasurement.waves.height。然后，该示例运行聚合管道：

const pipeline = [
  {
    $setWindowFields: {
      partitionBy: "$callLetters",
      sortBy: { ts: 1 },
      output: {
        temperatureAvg: {
          $avg: "$airTemperature.value",
          window: {
            range: [-1, "current"],
            unit: "month"
          }
        },
        totalWaveHeight: {
          $sum: "$waveMeasurement.waves.height",
          window: {
            range: [-1, "current"],
            unit: "month"
          }
        }
      }
    }
  },
];

const cursor = collection.aggregate(pipeline);
return cursor;

Tip

For an additional example about IOT Power Consumption, see the Practical MongoDB Aggregations e-book.有关物联网功耗的更多示例，请参阅实用MongoDB聚合电子书。