Summary and aggregation
- Last UpdatedJul 02, 2026
- 4 minute read
The summary and aggregation feature helps you compute grouped counts and numeric rollups directly in Knowledge Graph.
Use these query fields:
-
summarizeEntities(...) for entity data
-
summarizeEvents(...) for event data
Both operations let you:
-
Filter the population first (input for entities, where for events)
-
Group by property and/or relationship
-
Aggregate numeric properties (minimum, maximum, average, sum, count)
When to use summary and aggregation
Use summary queries when you need:
-
Distribution counts by category (for example, status, site, or relationship target)
-
Fast numeric rollups (for example, average pressure or total runtime)
-
Reduced payload size compared to returning full entity/event records
Field reference
summarizeEntities
summarizeEntities(
input: EntityFilterInput
groupByProperties: [GroupByProperty]
groupByRelationships: [GroupByRelationship]
summarizeByProperty: [SummarizeByProperty]!
): EntitySummaryResult
summarizeEvents
summarizeEvents(
where: EventFilter
groupByProperties: [GroupByProperty]
groupByRelationships: [GroupByRelationship]
summarizeByProperty: [SummarizeByProperty]!
): EventSummaryResult
Grouping inputs
input GroupByProperty {
propertyId: String
typeId: String
}
input GroupByRelationship {
relationshipId: String
typeId: String
}
Aggregation input
input SummarizeByProperty {
propertyId: String
typeId: String
uom: String
}
Tip: summarizeByProperty is required and must contain at least one property to aggregate.
Example: Entity summary grouped by a property
This example groups pumps by siteCode and aggregates pressureRate.
query {
summarizeEntities(
input: {
filter: {
where: {
className: { eq: "Pump" }
}
}
}
groupByProperties: [
{ propertyId: "siteCode", typeId: "Core.Asset" }
]
summarizeByProperty: [
{ propertyId: "pressureRate", typeId: "Core.Asset", uom: "bar" }
]
) {
summaries {
count
groupProperties {
typeId
groupProperty {
id
value
typeCode
}
}
propertySummaries {
id
typeId
uom
count
minimum
maximum
average
sum
}
}
summaryErrors {
message
propertyId
typeId
reason
resolution
}
responseContext {
requestTime
}
}
}
Expected result pattern:
{
"data": {
"summarizeEntities": {
"summaries": [
{
"count": 12,
"groupProperties": [
{
"typeId": "Core.Asset",
"groupProperty": {
"id": "siteCode",
"value": 101,
"typeCode": "INT32"
}
}
],
"propertySummaries": [
{
"id": "pressureRate",
"typeId": "Core.Asset",
"uom": "bar",
"count": 12,
"minimum": 3.1,
"maximum": 9.8,
"average": 6.4,
"sum": 76.8
}
]
},
{
"count": 8,
"groupProperties": [
{
"typeId": "Core.Asset",
"groupProperty": {
"id": "siteCode",
"value": 202,
"typeCode": "INT32"
}
}
],
"propertySummaries": [
{
"id": "pressureRate",
"typeId": "Core.Asset",
"uom": "bar",
"count": 8,
"minimum": 2.9,
"maximum": 8.4,
"average": 5.7,
"sum": 45.6
}
]
}
],
"summaryErrors": [],
"responseContext": {
"requestTime": "2026-04-07T18:35:14Z"
}
}
}
}
Example: Event summary grouped by relationship
This example groups active events by a parent relationship and aggregates durationHours.
query {
summarizeEvents(
where: {
state: ACTIVE
startTime: { gt: "2026-01-01T00:00:00Z" }
}
groupByRelationships: [
{ relationshipId: "parent", typeId: "Core.Event" }
]
summarizeByProperty: [
{ propertyId: "durationHours", typeId: "Core.Event", uom: "h" }
]
) {
summaries {
count
groupRelationships {
relationshipId
typeId
targets {
id
targetBase
relationshipType
}
}
propertySummaries {
id
typeId
uom
count
minimum
maximum
average
sum
}
}
summaryErrors {
message
propertyId
typeId
reason
resolution
}
}
}
Expected result pattern:
{
"data": {
"summarizeEvents": {
"summaries": [
{
"count": 6,
"groupRelationships": [
{
"relationshipId": "parent",
"typeId": "Core.Event",
"targets": [
{
"id": "line-01",
"targetBase": "ENTITY",
"relationshipType": "PARENT"
}
]
}
],
"propertySummaries": [
{
"id": "durationHours",
"typeId": "Core.Event",
"uom": "h",
"count": 6,
"minimum": 0.2,
"maximum": 3.4,
"average": 1.1,
"sum": 6.6
}
]
}
],
"summaryErrors": []
}
}
}
Example: Event summary grouped by a property
This example groups active events by severityCode and aggregates durationHours.
query {
summarizeEvents(
where: {
state: ACTIVE
startTime: { gt: "2026-01-01T00:00:00Z" }
}
groupByProperties: [
{ propertyId: "severityCode", typeId: "Core.Event" }
]
summarizeByProperty: [
{ propertyId: "durationHours", typeId: "Core.Event", uom: "h" }
]
) {
summaries {
count
groupProperties {
typeId
groupProperty {
id
value
typeCode
}
}
propertySummaries {
id
typeId
uom
count
minimum
maximum
average
sum
}
}
summaryErrors {
message
propertyId
typeId
reason
resolution
}
}
}
Expected result pattern:
{
"data": {
"summarizeEvents": {
"summaries": [
{
"count": 14,
"groupProperties": [
{
"typeId": "Core.Event",
"groupProperty": {
"id": "severityCode",
"value": 1,
"typeCode": "INT32"
}
}
],
"propertySummaries": [
{
"id": "durationHours",
"typeId": "Core.Event",
"uom": "h",
"count": 14,
"minimum": 0.1,
"maximum": 2.8,
"average": 0.9,
"sum": 12.6
}
]
},
{
"count": 5,
"groupProperties": [
{
"typeId": "Core.Event",
"groupProperty": {
"id": "severityCode",
"value": 3,
"typeCode": "INT32"
}
}
],
"propertySummaries": [
{
"id": "durationHours",
"typeId": "Core.Event",
"uom": "h",
"count": 5,
"minimum": 1.2,
"maximum": 5.4,
"average": 2.7,
"sum": 13.5
}
]
}
],
"summaryErrors": []
}
}
}
Example: Reading summaryErrors
If a property cannot be aggregated (for example, incompatible type/UOM or missing metadata), the response can include summaryErrors.
{
"data": {
"summarizeEntities": {
"summaries": [
{
"count": 20,
"propertySummaries": []
}
],
"summaryErrors": [
{
"message": "Unable to summarize property.",
"propertyId": "flowState",
"typeId": "Core.Asset",
"reason": "Property type is not numeric.",
"resolution": "Use summarizeByProperty only with numeric properties."
}
]
}
}
}
Query design recommendations
-
Keep the filter selective before summarizing to improve latency.
-
Prefer one business question per summary query to keep results easy to interpret.
-
Include only required output fields to reduce payload size.
-
Use stable typeId + propertyId pairs in groupByProperties and summarizeByProperty.
-
Always inspect summaryErrors before trusting aggregates.