Docs Menu

$integral (aggregation)

On this page

  • Definition
  • Behavior
  • Example

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:

$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.

A string that specifies the time unit. Use one of these strings:

  • "week"
  • "day"
  • "hour"
  • "minute"
  • "second"
  • "millisecond"

If the sortBy field is not a date, you must omit a unit. If you specify a unit, you must specify a date in the sortBy field.

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

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.

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.

Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.