Advanced examples

The examples below use two shared datasets so you can follow the numbers end-to-end.

Reference data — sales dataset

Seven sale records, each with root-level properties salesperson (string), region (string), and amount (integer, "count" UoM):

Reference data — bakery dataset

Three baking records, each with root-level properties item (string), cooktime (TimeSpan), and quantity (integer, "count" UoM), plus a flour component with brand (string) and count (integer, "count" UoM):

Example 1 — Simple summary, no grouping

Summarize cooktime across all bakery records that have a quantity ≥ 0:

SummarizeQueryEventsRequest {
Filters: [
{ Property: { PropertyId: "quantity", Operation: GreaterThanOrEquals, Value: 0, Uom: "count" } }
]
PropertiesToSummarize: [
{ PropertyId: "cooktime" }
]
}

All three records match the filter. cooktime is a TimeSpan, so values are converted to seconds (25 min = 1500 s, 10 min = 600 s, 35 min = 2100 s).

Response — a single ResourceSummary with no group fields:

Example 2 — Group by a root property

Break down sales by region:

SummarizeQueryEventsRequest {
Filters: [
{ Property: { PropertyId: "amount", Operation: GreaterThanOrEquals, Value: 0, Uom: "count" } }
]
GroupByProperties: [ { PropertyId: "region" } ]
PropertiesToSummarize: [ { PropertyId: "amount" } ]
}

Response — one ResourceSummary per distinct region. Each entry's GroupProperties[0].GroupProperty.Value is the region string:

Example 3 — Group by a component property and summarize a root property

Group bakery records by the flour brand (inside the flour component) and aggregate root-level cooktime:

SummarizeQueryEventsRequest {
Filters: [
{ Property: { PropertyId: "quantity", Operation: GreaterThanOrEquals, Value: 0, Uom: "count" } }
]
GroupByProperties: [ { PropertyId: "brand", TypeId: "flour" } ]
PropertiesToSummarize: [ { PropertyId: "cooktime" } ]
}

Each of the three records has a distinct brand, so each forms its own group. Resources that have no flour component (or no brand property within it) would be excluded from all summaries entirely.

Response — one ResourceSummary per brand, GroupProperties[0].TypeId = "flour":

Example 4 — Multiple group-by properties (compound key)

Group sales by salesperson AND region simultaneously:

SummarizeQueryEventsRequest {
Filters: [
{ Property: { PropertyId: "amount", Operation: GreaterThanOrEquals, Value: 0, Uom: "count" } }
]
GroupByProperties: [
{ PropertyId: "salesperson" },
{ PropertyId: "region" }
]
PropertiesToSummarize: [ { PropertyId: "amount" } ]
}

Response — one ResourceSummary per (salesperson, region) pair. Each entry's GroupProperties contains two elements. Charlie has no south sales so no entry is produced for (charlie, south):

Reference data — Operations dataset

Two operation records with a shifts relationship pointing to shift records. Shift records store the productivity property being summarized.

Operations (the records being queried — Name starts with "op"):

Shifts (relationship targets):

Example 5 — Group by relationship target

Group the two operation records by each individual shift they are linked to via the shifts relationship:

SummarizeQueryEventsRequest {
Filters: [ { Property: { PropertyId: "Name", Operation: StartsWith, Value: "op" } } ]
GroupByRelationships: [ { RelationshipId: "shifts" } ]
PropertiesToSummarize: [ { PropertyId: "amount" } ]
}

Both oper1 and oper2 link to shift1, so shift1's group aggregates both records. The remaining shifts are each referenced by only one operation. ResourceSummary.GroupRelationships[0].Target.TargetId identifies the specific shift.

Response — one ResourceSummary per distinct shift target:

Example 6 — External relationship groups (parent-to-children)

Summarize shift records grouped by which operation they belong to. The shift records don't store a back-reference to their parent operation, so provide the parent→children mapping via InRelationshipGroups. Here the resources being queried and summarized are the shift records (not the operations):

SummarizeQueryEventsRequest {
Filters: [ { Property: { PropertyId: "productivity", Operation: GreaterThanOrEquals, Value: 0, Uom: "count" } } ]
PropertiesToSummarize: [ { PropertyId: "productivity" } ]
InRelationshipGroups: {
"oper1": { Id: "shifts", Targets: [ { TargetId: "shift1" }, { TargetId: "shift2" } ] },
"oper2": { Id: "shifts", Targets: [ { TargetId: "shift1" }, { TargetId: "shift3" }, { TargetId: "shift4" } ] }
}
}

shift1 belongs to both oper1 and oper2, so it contributes to both groups independently. ResourceSummary.InRelationshipGroups carries the group key ("oper1" or "oper2").

Response — one ResourceSummary per group key:

External groups can also be combined with GroupByProperties to produce a summary per (group key, property value) pair.

Example 7 — UoM conversion

Summarize multiple properties, requesting specific output units per property:

SummarizeQueryEventsRequest {
Filters: [ ... ]
PropertiesToSummarize: [
{ PropertyId: "length", Uom: "ft" }, // stored in metres, converted to feet
{ PropertyId: "width", Uom: "cm" }, // stored in inches, converted to centimetres
{ PropertyId: "height" } // no Uom — uses stored unit
]
}

Conversions are applied before aggregation, so Min, Max, Sum, and Average are all in the requested unit. PropertySummary.Uom reflects the output unit. See When no UoM is specified about mixing incompatible units.

Example 8 — Summarizing multiple properties simultaneously

Multiple entries in PropertiesToSummarize produce multiple PropertySummary entries inside the same ResourceSummary:

PropertiesToSummarize: [
{ PropertyId: "cooktime" },
{ PropertyId: "quantity", Uom: "count" }
]

Using the bakery dataset with no grouping:

If one property fails (for example, is non-numeric), its error is reported in SummaryErrors while the other properties still produce valid summaries.