Aggregation Queries

Aggregation queries compute summary values (averages, totals, extremes) across time-series data points instead of returning individual rows. Use these when you need calculated metrics rather than raw data — for example, the average voltage over the last hour or the total energy produced per machine.

OctoMesh supports two aggregation query types:

• Aggregation Query — computes aggregated values across all matching data points
• Grouped Aggregation Query — computes aggregated values grouped by one or more columns (similar to SQL GROUP BY)

Aggregation Types

Type	Description	Example
AVG	Average value	Average voltage over a time range
MIN	Minimum value	Lowest temperature reading
MAX	Maximum value	Peak power consumption
COUNT	Number of data points	Number of measurements recorded
SUM	Sum of values	Total energy produced

---

Aggregation Query

The aggregation query computes a single aggregated result across all matching data points. Use the transientStreamDataAggregationQuery field.

Basic Usage

query {
  streamData {
    transientStreamDataAggregationQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG },
        { attributePath: "voltage", aggregationType: MIN },
        { attributePath: "voltage", aggregationType: MAX }
      ]
    ) {
      totalCount
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "streamData": {
      "transientStreamDataAggregationQuery": {
        "totalCount": 1,
        "items": [
          {
            "cells": {
              "items": [
                { "attributePath": "Avg_voltage", "value": 230.4 },
                { "attributePath": "Min_voltage", "value": 218.7 },
                { "attributePath": "Max_voltage", "value": 242.1 }
              ]
            }
          }
        ]
      }
    }
  }
}

The result contains a single row with one cell per aggregation column. The attributePath in the response is prefixed with the aggregation type (e.g., Avg_voltage, Min_voltage).

Parameters

Parameter	Type	Required	Description
ckId	String!	Yes	The CK type to query
columnPaths	[StreamDataQueryColumnInput!]!	Yes	Columns with aggregation type
arg	StreamDataArguments	No	Time range and limit overrides
fieldFilter	[FieldFilter]	No	Field-level comparison filters
rtIds	[OctoObjectId]	No	Scope to specific runtime entity IDs
first	Int	No	Maximum number of items to return
after	String	No	Pagination cursor

StreamDataQueryColumnInput

Each column specifies the attribute to aggregate and the aggregation function to apply:

Field	Type	Required	Description
attributePath	String!	Yes	The data stream attribute to aggregate
aggregationType	AggregationType!	Yes	AVG, MIN, MAX, COUNT, or SUM

With Time Range and Entity Filter

query {
  streamData {
    transientStreamDataAggregationQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG },
        { attributePath: "power", aggregationType: SUM }
      ]
      arg: {
        queryMode: DEFAULT
        from: "2024-03-21T00:00:00Z"
        to: "2024-03-22T00:00:00Z"
      }
      rtIds: ["65dc6d24cc529cdc46c84fcc"]
    ) {
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Counting Data Points

Use COUNT to determine how many data points exist for a given attribute:

query {
  streamData {
    transientStreamDataAggregationQuery(
      ckId: "Industry.Energy/EnergyMeter"
      columnPaths: [
        { attributePath: "voltage", aggregationType: COUNT }
      ]
      arg: {
        queryMode: DEFAULT
        from: "2024-03-21T00:00:00Z"
        to: "2024-03-22T00:00:00Z"
      }
    ) {
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

---

Grouped Aggregation Query

A grouped aggregation query computes aggregated values grouped by one or more columns — equivalent to a SQL GROUP BY clause. Use the transientStreamDataGroupedAggregationQuery field.

Basic Usage

This example computes the average voltage per entity:

query {
  streamData {
    transientStreamDataGroupedAggregationQuery(
      ckId: "Industry.Energy/EnergyMeter"
      groupByColumnPaths: ["rtId"]
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG },
        { attributePath: "power", aggregationType: MAX }
      ]
    ) {
      totalCount
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "streamData": {
      "transientStreamDataGroupedAggregationQuery": {
        "totalCount": 3,
        "items": [
          {
            "cells": {
              "items": [
                { "attributePath": "rtId", "value": "65dc6d24cc529cdc46c84fcc" },
                { "attributePath": "Avg_voltage", "value": 230.4 },
                { "attributePath": "Max_power", "value": 1580.0 }
              ]
            }
          },
          {
            "cells": {
              "items": [
                { "attributePath": "rtId", "value": "65dc6d24cc529cdc46c84fcd" },
                { "attributePath": "Avg_voltage", "value": 228.9 },
                { "attributePath": "Max_power", "value": 1620.5 }
              ]
            }
          },
          {
            "cells": {
              "items": [
                { "attributePath": "rtId", "value": "65dc6d24cc529cdc46c84fce" },
                { "attributePath": "Avg_voltage", "value": 231.2 },
                { "attributePath": "Max_power", "value": 1490.3 }
              ]
            }
          }
        ]
      }
    }
  }
}

Each row in the result represents one group. The grouping column values appear in the cells alongside the aggregated values.

Parameters

Parameter	Type	Required	Description
ckId	String!	Yes	The CK type to query
groupByColumnPaths	[String!]!	Yes	Attribute paths to group by
columnPaths	[StreamDataQueryColumnInput!]!	Yes	Columns with aggregation type
arg	StreamDataArguments	No	Time range and limit overrides
fieldFilter	[FieldFilter]	No	Field-level comparison filters
rtIds	[OctoObjectId]	No	Scope to specific runtime entity IDs
first	Int	No	Maximum number of items to return
after	String	No	Pagination cursor

Grouping by Multiple Columns

You can group by more than one column. This example groups by both entity and CK type:

query {
  streamData {
    transientStreamDataGroupedAggregationQuery(
      ckId: "Industry.Energy/EnergyMeter"
      groupByColumnPaths: ["rtId", "ckTypeId"]
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG }
      ]
      arg: {
        queryMode: DEFAULT
        from: "2024-03-21T00:00:00Z"
        to: "2024-03-22T00:00:00Z"
      }
    ) {
      totalCount
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

With Filters

Filters are applied before aggregation, limiting which data points are included in the calculation:

query {
  streamData {
    transientStreamDataGroupedAggregationQuery(
      ckId: "Industry.Energy/EnergyMeter"
      groupByColumnPaths: ["rtId"]
      columnPaths: [
        { attributePath: "voltage", aggregationType: AVG }
      ]
      fieldFilter: [
        { attributePath: "voltage", operator: GREATER_THAN, comparisonValue: 0 }
      ]
    ) {
      totalCount
      items {
        cells {
          items {
            attributePath
            value
          }
        }
      }
    }
  }
}

This computes the average voltage per entity, but only considering data points where the voltage is greater than zero.

---

Use Cases

Scenario	Query Type	Example
Overall average for a KPI widget	Aggregation	Average temperature across all sensors
Per-machine production totals	Grouped Aggregation	Total output grouped by rtId
Data quality check	Aggregation with COUNT	Count of readings in a time range
Comparison dashboard	Grouped Aggregation	Min/max/avg per entity for side-by-side display