Skip to main content

AggregateStreamData@1

Node AggregateStreamData@1 condenses the columns of a stream data archive into key figures over a time range — the sum of a month's energy, the maximum data quality in that month. It is the sibling of GetStreamData@1, which returns the rows themselves.

The node writes a query result to targetPath: one column per key figure and, when groupBy is used, one row per group.

Adapter Prerequisites​

Node Configuration​

For fields targetPath, targetValueWriteMode, and targetValueKind, see Overview. Field path is not used in this node.

transformations:
  - type: AggregateStreamData@1
    archiveRtId: 68a1f0c5de73e7b175575401 # Runtime ID of the archive to read from (must be activated)
    aggregations: # The key figures to compute, at least one
      - attributePath: Energy
        function: Sum
      - attributePath: DataQuality
        function: Maximum
    groupBy: # Columns to group by, empty means a single result row
      - rtId
    wellKnownNames: # Restrict to source entities with these well-known names
      - METER-4711
    wellKnownNamesPath: $.meters # Alternative: read the well-known names from the payload
    rtIds: # Restrict to these source entities
      - 68a2b1c4de73e7b175575402
    rtIdsPath: $.rtIds # Alternative: read the runtime IDs from the payload
    fieldFilters: # Additional filters, combined with AND
      - attributePath: DataQuality
        operator: GreaterEqualsThan
        comparisonValue: 90
    from: 2026-07-01T00:00:00 # Start of the aggregated time range (UTC)
    fromPath: $.from # Alternative: read the start of the time range from the payload
    to: 2026-08-01T00:00:00 # End of the aggregated time range (UTC)
    toPath: $.to # Alternative: read the end of the time range from the payload
    requireGapFree: true # Only aggregate when the range is fully covered by data
    expectedInterval: PT15M # Interval the completeness check counts in
    maxGapScanRows: 200000 # Row cap for the completeness check
    targetPath: $.monthly # Path where the key figures are stored in the payload

Parameters​

ParameterTypeRequiredDescription
archiveRtIdstringYesRuntime ID of the archive to read from. The archive must be activated
aggregationsarray of AggregationColumnDtoYesThe key figures to compute. At least one entry; the same column may appear several times with different functions
groupByarray of stringNoColumns to group by, e.g. rtId for one row per source entity. Empty means a single row
wellKnownNamesarray of stringNoRestricts the aggregation to source entities with these well-known names
wellKnownNamesPathstringNoJSONPath alternative to wellKnownNames; accepts a single value, an array, or a multi-match path
rtIdsarray of stringNoRestricts the aggregation to these source entities
rtIdsPathstringNoJSONPath alternative to rtIds
fieldFiltersarray of FieldFilterWithPathDtoNoAdditional filters on the archive's columns, combined with AND
fromdate/timeNoStart of the aggregated time range (UTC). Unset aggregates from the beginning of the archive
fromPathstringNoJSONPath to the start of the time range in the payload
todate/timeNoEnd of the aggregated time range (UTC). Unset aggregates to the end of the archive
toPathstringNoJSONPath to the end of the time range in the payload
requireGapFreebooleanNoOnly aggregate when every source entity delivered data for the whole time range
expectedIntervaldurationNoInterval the completeness check counts in, e.g. PT15M. Defaults to the archive's declared period
maxGapScanRowsintegerNoRow cap for the completeness check (default 200000), must be greater than zero

For the available filter operators, see GetRtEntitiesByType@1.

Aggregation columns​

ParameterTypeRequiredDescription
attributePathstringYesThe column to aggregate (e.g. Energy, Amount.Value)
functionenumYesThe aggregation function
comparisonValuestringNoReserved for state-based aggregations; ignored by the functions below

Supported functions are Count, Minimum, Maximum, Average and Sum.

note

TimeWeightedAverage and StateDuration are refused by this node: they need metadata the node cannot carry — a comparison value, or a raw archive's carry-forward path — and their result keys follow different rules. Use GetQueryById@1 with a persisted query that defines the aggregation per column.

Precedence and time zone​

Per value the literal wins over its JSONPath variant: from takes precedence over fromPath, to over toPath, wellKnownNames over wellKnownNamesPath and rtIds over rtIdsPath.

note

Timestamps are read as UTC. A value written without a time-zone offset (2026-07-01T00:00:00) is interpreted as UTC, not as the local time of the adapter host.

A path that resolves to nothing leaves the boundary open and logs a warning; a value that is present but not a date/time fails the node.

Column names​

The names in groupBy, fieldFilters and the attributePath values follow the same vocabulary as GetStreamData@1: Timestamp, WindowStart / WindowEnd (windowed archives only), WellKnownName, or any column the archive declares. A name that cannot be resolved fails the node instead of being ignored.

caution

On an aggregation the stakes are higher than on a read: a dropped filter would inflate the figure, and a dropped group-by column would collapse every group into a single row. That is why unknown names are refused rather than skipped.

Result Shape​

The result carries the group-by columns first, then one column per key figure. Without groupBy there is exactly one row — even when the storage returned nothing, in which case the values are null rather than the row being absent, so a downstream consumer always finds the shape it expects.

Aggregating the same attribute path more than once appends the function to the header, because a bare path header would not be unique:

Energy (Minimum) | Energy (Maximum)

Completeness Guard​

requireGapFree: true runs the coverage check of GetStreamData@1 before the aggregation, sharing its scan, row cap and interval fallback. If any entity is short, the node fails and names the affected series with how much is missing and where the first hole starts.

There are no partial results: an incomplete month must not return a figure that looks valid but is too low. The guard requires both time boundaries and a windowed archive (time-range or rollup).

Pitfalls of aggregated stream data
  • Sum is only correct over disjoint windows. Identical windows cannot occur — the storage layer merges them — but overlapping windows are legal and their overlapping section is counted twice. requireGapFree deliberately does not fail on them; it promises gap-freedom, not disjointness. To react to overlaps, evaluate hasOverlaps from the gap report of GetStreamData@1.
  • Average is arithmetic, not time-weighted. For windows of equal length (the quarter-hour case) both are identical; for variable window lengths a time-weighted average is the correct mean, which means GetQueryById@1.
  • No sorting, paging or row cap. These have no meaning for an aggregation and are therefore absent from the configuration rather than present and ignored.

Usage Example​

Sum up the energy consumed in a month per meter and report the maximum data quality in the same period — but only if the month is available without gaps:

triggers:
  - type: FromExecutePipelineCommand@1
transformations:
  - type: AggregateStreamData@1
    archiveRtId: 68a1f0c5de73e7b175575401
    aggregations:
      - attributePath: Energy
        function: Sum
      - attributePath: DataQuality
        function: Maximum
    groupBy:
      - rtId
    from: 2026-07-01T00:00:00
    to:   2026-08-01T00:00:00
    requireGapFree: true
    expectedInterval: PT15M
    targetPath: $.monthly
  - type: QueryResultToMarkdownTable@1
    path: $.monthly
    targetPath: $.table

Use Cases​

  • Billing: Determine the consumption of a billing period per meter, guarded against incomplete data
  • Key figure reporting: Compute monthly, weekly or shift-based totals, minima and maxima
  • Quality monitoring: Report the worst or the average data quality of a period
  • Threshold monitoring: Compute a key figure and branch on it in a following control node
  • Condensing before transfer: Send a few key figures instead of thousands of raw rows

See Also​