Specify what to summarize

message SummarizeByProperty {
string PropertyId = 1; // required
optional string TypeId = 2; // if set, scopes to that component; if omitted, root level only
optional string Uom = 3; // desired output unit of measure
}

Root vs. component properties

• Root property — omit TypeId. Summarization operates only on the property at the root level of each resource. Even if a component on the same resource has a property with the same ID, it is ignored.

• Component property — supply TypeId matching the component's type identifier. Summarization operates only on property values found within that component. Root-level values with the same PropertyId are ignored.

Property ID scoping is always strict. TypeId is the switch. Omitting it means root only; providing it means that component only. There is no mode that summarizes across both, or across multiple components, simultaneously.

Unit of measure conversion

Supply a Uom on SummarizeByProperty to request conversion of all values to a different unit before aggregation. The system converts each value before computing min, max, sum, and average, and the PropertySummary.Uom in the response reflects the output unit.

• TimeSpan/duration properties are always converted to seconds automatically, regardless of any Uom you supply. The response Uom will be "second".

When no Uom is specified

The output unit is determined lazily: the unit of the first resource encountered that has that property becomes the target unit for the entire summary. All subsequent resource values are then converted into that unit.

Note: Incompatible units will cause the entire request to fail. If resources store the same PropertyId with units from different dimensions (for example, "m" on one resource and "lb" on another), the conversion will throw an InvalidConversion error when the second resource is processed. This is not caught as a partial error — the whole SummarizeQuery call fails.

The safe practice is to always explicitly specify Uom on SummarizeByProperty whenever the dataset may contain mixed units for the same property ID. This ensures a known target unit and will fail fast and clearly if any stored unit cannot be converted to it (such as an incompatible dimension), rather than producing a silent mid-request failure.

This risk is most relevant when using root properties without a TypeId, since different resources can independently store any unit alongside a given property ID. Component properties scoped with TypeId are less prone to this if the component schema enforces a consistent unit.