OASIS OData TC - Vocabularies

Aggregation Vocabulary

Namespace: Org.OData.Aggregation.V1

Terms to describe which data in a given entity model can be aggregated, and how.

Related to the specification document OData-Data-Agg-v4.0.

Terms

Term Type Description
ApplySupported ApplySupportedType This entity set or collection supports the $apply system query option
ApplySupportedDefaults ApplySupportedBase Default support of the $apply system query option for all collection-valued resources in the container

Annotating term ApplySupported for a specific collection-valued resource overrides the default support with the specified properties using PATCH semantics:

  • Primitive or collection-valued properties specified in ApplySupported replace the corresponding properties specified in ApplySupportedDefaults
  • Complex-valued properties specified in ApplySupported override the corresponding properties specified in ApplySupportedDefaults using PATCH semantics recursively
  • Properties specified neither in ApplySupported nor in ApplySupportedDefaults have their default value
Groupable (Deprecated) Tag Deprecated in favor of ApplySupported/GroupableProperties
Aggregatable (Deprecated) Tag Deprecated in favor of ApplySupported/AggregatableProperties
CustomAggregate String Dynamic property that can be used in the aggregate transformation
This term MUST be applied with a Qualifier, the Qualifier value is the name of the dynamic property. The value of the annotation MUST be the qualified name of a primitive type. The aggregated value will be of that type.
ContextDefiningProperties [PropertyPath] The annotated property or custom aggregate is only well-defined in the context of these properties
The context-defining properties need either be part of the result entities, or be restricted to a single value by a pre-filter operation. Examples are postal codes within a country, or monetary amounts whose context is the unit of currency.
LeveledHierarchy [PropertyPath] Defines a leveled hierarchy (OData-Data-Agg-v4.0, section 5.5.1)
RecursiveHierarchy RecursiveHierarchyType Defines a recursive hierarchy (OData-Data-Agg-v4.0, section 5.5.2)
UpPath [String] The string values of the node identifiers in a path from the annotated node to a start node in a traversal of a recursive hierarchy
This instance annotation occurs in the result set after a traverse transformation (OData-Data-Agg-v4.0, section 6.2.2.2). A use case for this is traversal with multiple parents, when this annotation takes as value one parent node identifier followed by one grandparent node identifier and so on.
AvailableOnAggregates AvailableOnAggregatesType This function is available on aggregated entities if the RequiredProperties are still defined

Functions

isnode

Is the entity a node of the hierarchy specified by the parameter pair (HierarchyNodes, HierarchyQualifier)? (See OData-Data-Agg-v4.0, section 5.5.2.1)

If a node identifier passed to the function is null, the function returns null.

Parameter Type Description
HierarchyNodes [EntityType] A collection, given through a $root expression
HierarchyQualifier HierarchyQualifier
Node PrimitiveType? Node identifier of the putative node
→ Boolean?

isroot

Is the entity a root node of the hierarchy specified by the parameter pair (HierarchyNodes, HierarchyQualifier)?

If a node identifier passed to the function is null, the function returns null.

Parameter Type Description
HierarchyNodes [EntityType] A collection, given through a $root expression
HierarchyQualifier HierarchyQualifier
Node PrimitiveType? Node identifier of the putative root
→ Boolean?

isdescendant

Is the entity a descendant node of the ancestor node in the hierarchy specified by the parameter pair (HierarchyNodes, HierarchyQualifier) with at most the specified distance? (See OData-Data-Agg-v4.0, section 5.5.2.1)

If a node identifier passed to the function is null, the function returns null.

Parameter Type Description
HierarchyNodes [EntityType] A collection, given through a $root expression
HierarchyQualifier HierarchyQualifier
Node PrimitiveType? Node identifier of the putative descendant
Ancestor PrimitiveType? Node identifier of the ancestor node
MaxDistance Int16 Optional parameter
IncludeSelf Boolean Optional parameter: Whether to include the node itself in the result
→ Boolean?

isancestor

Is the entity an ancestor node of the descendant node in the hierarchy specified by the parameter pair (HierarchyNodes, HierarchyQualifier) with at most the specified distance? (See OData-Data-Agg-v4.0, section 5.5.2.1)

If a node identifier passed to the function is null, the function returns null.

Parameter Type Description
HierarchyNodes [EntityType] A collection, given through a $root expression
HierarchyQualifier HierarchyQualifier
Node PrimitiveType? Node identifier of the putative ancestor
Descendant PrimitiveType? Node identifier of the descendant node
MaxDistance Int16 Optional parameter
IncludeSelf Boolean Optional parameter: Whether to include the node itself in the result
→ Boolean?

issibling

Is the entity a sibling node of the other node in the hierarchy specified by the parameter pair (HierarchyNodes, HierarchyQualifier)? (See OData-Data-Agg-v4.0, section 5.5.2.1)

A node is not a sibling of itself. If a node identifier passed to the function is null, the function returns null.

Parameter Type Description
HierarchyNodes [EntityType] A collection, given through a $root expression
HierarchyQualifier HierarchyQualifier
Node PrimitiveType? Node identifier of the putative sibling
Other PrimitiveType? Node identifier of the other node
→ Boolean?

isleaf

Is the entity a leaf node in the hierarchy specified by the parameter pair (HierarchyNodes, HierarchyQualifier)? (See OData-Data-Agg-v4.0, section 5.5.2.1)

If a node identifier passed to the function is null, the function returns null.

Parameter Type Description
HierarchyNodes [EntityType] A collection, given through a $root expression
HierarchyQualifier HierarchyQualifier
Node PrimitiveType? Node identifier of the putative leaf
→ Boolean?

rollupnode

During rolluprecursive for a hierarchy node, this function returns the node

This function may only occur in the second parameter of a groupby transformation whose first parameter contains rolluprecursive(...). It is evaluated as part of the transformation R(x) in the "rolluprecursive algorithm" (OData-Data-Agg-v4.0, section 6.3). Its behavior is undefined outside of this algorithm.

Sales?$apply=groupby((rolluprecursive(...)), filter(SalesOrganization eq Aggregation.rollupnode())/aggregate(...))

constructs a rollup that contains aggregates per hierarchy node while excluding descendants from the aggregation.

Parameter Type Description
Position Int16 Optional parameter: Position N among the rolluprecursive operators in the first argument of groupby
Every instance in the output set of a groupby transformation with M rolluprecursive operators has M relationships to M nodes in M recursive hierarchies. This function returns the node x with path r to the root in relationship number N. If several such groupby transformations are nested, this function refers to the innermost one.
→ EntityType

ApplySupportedBase

Services that do not fully implement a certain aggregation-related functionality may document this by annotating the ApplySupported or ApplySupportedDefaults annotation with a description.

Derived Types:

Property Type Description
Transformations [Transformation] Transformations that can be used in $apply
CustomAggregationMethods [String] Qualified names of custom aggregation methods that can be used in aggregate(...with...)
Rollup RollupType The service supports rollup hierarchies in a groupby transformation
From Boolean The service supports the from keyword in an aggregate transformation

ApplySupportedType: ApplySupportedBase

Property Type Description
Transformations [Transformation] Transformations that can be used in $apply
CustomAggregationMethods [String] Qualified names of custom aggregation methods that can be used in aggregate(...with...)
Rollup RollupType The service supports rollup hierarchies in a groupby transformation
From Boolean The service supports the from keyword in an aggregate transformation
PropertyRestrictions (Deprecated) Boolean Deprecated since Groupable and Aggregatable are deprecated
GroupableProperties [AnyPropertyPath] A non-empty collection indicates that only the listed properties of the annotated target are supported by the groupby transformation
AggregatableProperties [AggregatablePropertyType] A non-empty collection indicates that only the listed properties of the annotated target can be used in the aggregate transformation, optionally restricted to the specified aggregation methods

AggregatablePropertyType

Property Type Description
Property PropertyPath Aggregatable property
SupportedAggregationMethods [AggregationMethod] Standard and custom aggregation methods that can be applied to the property. If omitted, all aggregation methods can be applied
RecommendedAggregationMethod AggregationMethod? Recommended method for aggregating values of the property

Transformation

Type: String

A transformation that can be used in $apply

Allowed Value Description
aggregate OData-Data-Agg-v4.0, section 3.2.1
groupby OData-Data-Agg-v4.0, section 3.2.3
concat OData-Data-Agg-v4.0, section 3.2.2
identity OData-Data-Agg-v4.0, section 3.4.1
filter OData-Data-Agg-v4.0, section 3.3.2
search OData-Data-Agg-v4.0, section 3.3.4
nest OData-Data-Agg-v4.0, section 3.5.2
addnested OData-Data-Agg-v4.0, section 3.4.3
join OData-Data-Agg-v4.0, section 3.5.1
outerjoin OData-Data-Agg-v4.0, section 3.5.1
compute OData-Data-Agg-v4.0, section 3.4.2
bottomcount OData-Data-Agg-v4.0, section 3.3.1.1
bottomsum OData-Data-Agg-v4.0, section 3.3.1.3
bottompercent OData-Data-Agg-v4.0, section 3.3.1.2
topcount OData-Data-Agg-v4.0, section 3.3.1.1
topsum OData-Data-Agg-v4.0, section 3.3.1.3
toppercent OData-Data-Agg-v4.0, section 3.3.1.2
orderby OData-Data-Agg-v4.0, section 3.3.3
top OData-Data-Agg-v4.0, section 3.3.6
skip OData-Data-Agg-v4.0, section 3.3.5
ancestors OData-Data-Agg-v4.0, section 6.2.1
descendants OData-Data-Agg-v4.0, section 6.2.1
traverse OData-Data-Agg-v4.0, section 6.2.2

AggregationMethod

Type: String

Standard or custom aggregation method

Custom aggregation methods MUST use a namespace-qualified name, that is contain at least one dot.

Allowed Value Description
sum Can be applied to numeric values to return the sum of the non-null values, or null if there are no non-null values or the input set is empty
min Can be applied to values with a totally ordered domain to return the smallest of the non-null values, or null if there are no non-null values or the input set is empty
max Can be applied to values with a totally ordered domain to return the largest of the non-null values, or null if there are no non-null values or the input set is empty
average Can be applied to numeric values to return the sum of the non-null values divided by the count of the non-null values, or null if there are no non-null values or the input set is empty
countdistinct Counts the distinct values, omitting any null values
For navigation properties, it counts the distinct entities in the union of all entities related to entities in the input set. For collection-valued primitive properties, it counts the distinct items in the union of all collection values in the input set.

RollupType

The number of rollup or rolluprecursive operators allowed in a groupby transformation

Member Value Description
None 0 No support for rollup or rolluprecursive
SingleHierarchy 1 Only one rollup or rolluprecursive operator per groupby
MultipleHierarchies 2 Full support for rollup and rolluprecursive

RecursiveHierarchyType

Property Type Description
NodeProperty PropertyPath Primitive property holding the node identifier
ParentNavigationProperty NavigationPropertyPath Property for navigating to the parent node(s). Its type MUST be the entity type annotated with this term, and it MUST be collection-valued or nullable single-valued.

HierarchyQualifier

Type: String

Qualifier of a RecursiveHierarchy annotation

Every recursive hierarchy function defined in this vocabulary has

HierarchyQualifier is the qualifier of a RecursiveHierarchy annotation on the entity type of the collection given by the HierarchyNodes parameter. This specifies a recursive hierarchy that is evaluated by the function.

AvailableOnAggregatesType

Property Type Description
RequiredProperties [PropertyPath] Properties required to apply this function

Capabilities.NavigationRestrictions that make use of the additional properties in this subtype are deprecated in favor of ApplySupported and CustomAggregate

CustomAggregateType (Deprecated)

Deprecated since NavigationPropertyAggregationCapabilities is also deprecated