# $integral (aggregation)

On this page

## Definition

*New in version 5.0*.

`$integral`

¶

Returns the approximation of the area under a curve, which is calculated using the trapezoidal rule where each set of adjacent documents form a trapezoid using the:

- sortBy field values in the
`$setWindowFields`

stage for the integration intervals. - input field expression result values in
`$integral`

for the y axis values.

`$integral`

is only available in the
`$setWindowFields`

stage.

`$integral`

syntax:

{ $integral: { input: <expression>, unit: <time unit> } }

`$integral`

takes a document with these fields:

Field | Description |
---|---|

Specifies the expression to evaluate. You must provide an expression that returns a number. | |

## Behavior

If you omit a window, a default window with unbounded upper and lower limits is used.

## Example

Create a `powerConsumption`

collection that contains electrical power
usage in kilowatts measured by meter devices at 30 second intervals:

db.powerConsumption.insertMany( [ { powerMeterID: "1", timeStamp: new Date( "2020-05-18T14:10:30Z" ), kilowatts: 2.95 }, { powerMeterID: "1", timeStamp: new Date( "2020-05-18T14:11:00Z" ), kilowatts: 2.7 }, { powerMeterID: "1", timeStamp: new Date( "2020-05-18T14:11:30Z" ), kilowatts: 2.6 }, { powerMeterID: "1", timeStamp: new Date( "2020-05-18T14:12:00Z" ), kilowatts: 2.98 }, { powerMeterID: "2", timeStamp: new Date( "2020-05-18T14:10:30Z" ), kilowatts: 2.5 }, { powerMeterID: "2", timeStamp: new Date( "2020-05-18T14:11:00Z" ), kilowatts: 2.25 }, { powerMeterID: "2", timeStamp: new Date( "2020-05-18T14:11:30Z" ), kilowatts: 2.75 }, { powerMeterID: "2", timeStamp: new Date( "2020-05-18T14:12:00Z" ), kilowatts: 2.82 } ] )

This example uses `$integral`

in the `$setWindowFields`

stage to output the energy consumption in kilowatt-hours measured
by each meter device:

db.powerConsumption.aggregate( [ { $setWindowFields: { partitionBy: "$powerMeterID", sortBy: { timeStamp: 1 }, output: { powerMeterKilowattHours: { $integral: { input: "$kilowatts", unit: "hour" }, window: { range: [ "unbounded", "current" ], unit: "hour" } } } } } ] )

In the example:

`partitionBy: "$powerMeterID"`

partitions the documents in the collection by`powerMeterID`

.`sortBy: { timeStamp: 1 }`

sorts the documents in each partition by`timeStamp`

in ascending order (`1`

), so the earliest`timeStamp`

is first.`output`

sets the`kilowatts`

integral value in a new field called`powerMeterKilowattHours`

using`$integral`

that is run in a range window.- The input expression is set to
`"$kilowatts"`

, which is used for the y axis values in the integral calculation. - The
`$integral`

unit is set to`"hour"`

for the`timeStamp`

field, which means`$integral`

returns the kilowatt-hours energy consumption. - The window contains documents
between an
`unbounded`

lower limit and the`current`

document in the output. This means`$integral`

returns the total kilowatt-hours energy consumption for the documents from the beginning of the partition, which is the first data point in the partition for each power meter, to the timestamp of the current document in the output.

- The input expression is set to

In this example output, the energy consumption measured by meters 1 and
2 are shown in the `powerMeterKilowattHours`

field:

{ "_id" : ObjectId("60cbdc3f833dfeadc8e62863"), "powerMeterID" : "1", "timeStamp" : ISODate("2020-05-18T14:10:30Z"), "kilowatts" : 2.95, "powerMeterKilowattHours" : 0 } { "_id" : ObjectId("60cbdc3f833dfeadc8e62864"), "powerMeterID" : "1", "timeStamp" : ISODate("2020-05-18T14:11:00Z"), "kilowatts" : 2.7, "powerMeterKilowattHours" : 0.023541666666666666 } { "_id" : ObjectId("60cbdc3f833dfeadc8e62865"), "powerMeterID" : "1", "timeStamp" : ISODate("2020-05-18T14:11:30Z"), "kilowatts" : 2.6, "powerMeterKilowattHours" : 0.045625 } { "_id" : ObjectId("60cbdc3f833dfeadc8e62866"), "powerMeterID" : "1", "timeStamp" : ISODate("2020-05-18T14:12:00Z"), "kilowatts" : 2.98, "powerMeterKilowattHours" : 0.068875 } { "_id" : ObjectId("60cbdc3f833dfeadc8e62867"), "powerMeterID" : "2", "timeStamp" : ISODate("2020-05-18T14:10:30Z"), "kilowatts" : 2.5, "powerMeterKilowattHours" : 0 } { "_id" : ObjectId("60cbdc3f833dfeadc8e62868"), "powerMeterID" : "2", "timeStamp" : ISODate("2020-05-18T14:11:00Z"), "kilowatts" : 2.25, "powerMeterKilowattHours" : 0.019791666666666666 } { "_id" : ObjectId("60cbdc3f833dfeadc8e62869"), "powerMeterID" : "2", "timeStamp" : ISODate("2020-05-18T14:11:30Z"), "kilowatts" : 2.75, "powerMeterKilowattHours" : 0.040625 } { "_id" : ObjectId("60cbdc3f833dfeadc8e6286a"), "powerMeterID" : "2", "timeStamp" : ISODate("2020-05-18T14:12:00Z"), "kilowatts" : 2.82, "powerMeterKilowattHours" : 0.06383333333333334 }

For an additional example about IOT Power Consumption, see the Practical MongoDB Aggregations e-book.