Grouping results

Without any grouping fields, all matching resources are folded into a single ResourceSummary. Grouping splits that pool into one summary per unique combination of group key values.

Group by property

message GroupByProperty {
string PropertyId = 1;
optional string TypeId = 2; // scopes to a component, same as SummarizeByProperty
}

Each ResourceSummary in the response will carry a GroupProperties entry whose GroupProperty.Value identifies the bucket. Resources that do not have the group-by property are excluded from all groups (they do not appear in any summary).

Multiple GroupByProperty entries produce a Cartesian-style breakdown. Each unique combination of group-by values produces its own ResourceSummary. The response includes the full tuple of group values in ResourceSummary.GroupProperties.

Example — sales data grouped by salesperson and region:

salesperson|region|amount
alice |north |1200
alice |south | 200
bob |north | 400
bob |south | 400
charlie |north | 600
→ 5 ResourceSummary entries, one per (salesperson, region) pair

Group-by values are case-insensitive. Resources whose group-by property holds "alice" and "ALICE" are placed in the same bucket. Note that the value echoed back in the response reflects the actual stored value of the first matching resource in that group (case is preserved as stored).

Group by relationship

message GroupByRelationship {
string RelationshipId = 1;
optional string TypeId = 2;
}

Groups resources by the individual targets of a named relationship. Each unique relationship target produces its own ResourceSummary, and the response's GroupRelationships entry identifies the target. A resource that has multiple targets for the same relationship will appear in multiple groups.

Group by parent entity (events)

Events store their parent entity's ID in the Parent root field. To roll up event summaries per event, add Parent as a group-by relationship:

GroupByRelationships: [ { RelationshipId: "Parent" } ]

Each ResourceSummary in the response will represent one parent entity, and GroupRelationships[0].GroupRelationships.Value will be that entity's ID.

Combine property and relationship groups

GroupByProperties and GroupByRelationships can be used together. Each unique combination of (property values, relationship targets) produces its own summary.

External relationship groups

The InRelationshipGroups field solves the problem of grouping resources by a parent that doesn't have a direct relationship stored on the resource itself. You provide the mapping externally:

InRelationshipGroups: {
"oper1": Relationship { Id: "shifts", Targets: [ { TargetId: "shift1" }, { TargetId: "shift2" } ] },
"oper2": Relationship { Id: "shifts", Targets: [ { TargetId: "shift1" }, { TargetId: "shift3" }, { TargetId: "shift4" } ] }
}

The map key (for example, "oper1") becomes the group identifier echoed back in ResourceSummary.InRelationshipGroups. Resources whose IDs are listed in the Targets of a group's Relationship are included in that group's summary.

• A resource can appear in more than one external group if its ID appears in multiple entries.

• External groups can be combined with GroupByProperties. In that case the result is the intersection: one summary per (external group key, property value) combination.

• If a target ID listed in the map doesn't match any resource that passed the filters, it simply contributes nothing to that group's count.