$integral (aggregation)
On this page
Definition
New in version 5.0.
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 bypowerMeterID
.sortBy: { timeStamp: 1 }
sorts the documents in each partition bytimeStamp
in ascending order (1
), so the earliesttimeStamp
is first.output
sets thekilowatts
integral value in a new field calledpowerMeterKilowattHours
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 thetimeStamp
field, which means$integral
returns the kilowatt-hours energy consumption.The window contains documents between an
unbounded
lower limit and thecurrent
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.
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 }
Tip
See also:
For an additional example about IOT Power Consumption, see the Practical MongoDB Aggregations e-book.