diff --git a/vocabularies/Analytics.json b/vocabularies/Analytics.json index 727cd3ae1..365f816cb 100644 --- a/vocabularies/Analytics.json +++ b/vocabularies/Analytics.json @@ -12,6 +12,9 @@ }, "https://sap.github.io/odata-vocabularies/vocabularies/Common.json": { "$Include": [{ "$Namespace": "com.sap.vocabularies.Common.v1", "$Alias": "Common" }] + }, + "https://sap.github.io/odata-vocabularies/vocabularies/Hierarchy.json": { + "$Include": [{ "$Namespace": "com.sap.vocabularies.Hierarchy.v1", "$Alias": "Hierarchy" }] } }, "com.sap.vocabularies.Analytics.v1": { @@ -231,7 +234,11 @@ "@Core.OptionalParameter": { "DefaultValue": "false" } } ], - "$ReturnType": { "$Collection": true, "$Type": "Edm.EntityType" } + "$ReturnType": { + "$Collection": true, + "$Type": "Edm.EntityType", + "@Core.Description": "Output set including the instance annotation [`LevelInformation`](#LevelInformation)" + } } ], "AutoExpandLevel": { @@ -257,6 +264,14 @@ { "Value": "asc", "@Core.Description": "Sort in ascending order" }, { "Value": "desc", "@Core.Description": "Sort in descending order" } ] + }, + "LevelInformation": { + "$Kind": "Term", + "$Type": "Hierarchy.HierarchyType", + "$AppliesTo": ["EntityType"], + "@Common.Experimental": true, + "@Common.IsInstanceAnnotation": true, + "@Core.Description": "Information about grouping levels in the result set of an analytical request" } } } diff --git a/vocabularies/Analytics.md b/vocabularies/Analytics.md index 84c59a50a..a9c6e5599 100644 --- a/vocabularies/Analytics.md +++ b/vocabularies/Analytics.md @@ -8,89 +8,90 @@ Terms for annotating analytical resources Term|Type|Description :---|:---|:---------- -[Dimension](./Analytics.xml#L41:~:text=Deprecated in favor of [`AnalyticalContext/Dimension`](#AnalyticalContext) -[Measure](./Analytics.xml#L53:~:text=Deprecated in favor of [`AnalyticalContext/Measure`](#AnalyticalContext) -[AccumulativeMeasure](./Analytics.xml#L65:~:text=Deprecated in favor of [`AnalyticalContext/AccumulativeMeasure`](#AnalyticalContext) -[RolledUpPropertyCount](./Analytics.xml#L77:~:text=Number of properties in the entity instance that have been aggregated away -[DrillURL](./Analytics.xml#L83:~:text=URL to retrieve more detailed data related to a node of a recursive hierarchy. Annotations with this term MUST include a qualifier to select the hierarchy for which the drill URL is provided. -[PlanningAction](./Analytics.xml#L95:~:text=Processes or generates plan data. Its logic may have side-effects on entity sets. -[AggregatedProperties](./Analytics.xml#L103:~:text=Deprecated in favor of [`AggregatedProperty`](#AggregatedProperty) -[AggregatedProperty](./Analytics.xml#L121:~:text=Dynamic property for aggregate expression with specified aggregation method defined on the annotated entity type. -[AnalyticalContext](./Analytics.xml#L141:~:text=Collection of properties that define an analytical context +[Dimension](./Analytics.xml#L44:~:text=Deprecated in favor of [`AnalyticalContext/Dimension`](#AnalyticalContext) +[Measure](./Analytics.xml#L56:~:text=Deprecated in favor of [`AnalyticalContext/Measure`](#AnalyticalContext) +[AccumulativeMeasure](./Analytics.xml#L68:~:text=Deprecated in favor of [`AnalyticalContext/AccumulativeMeasure`](#AnalyticalContext) +[RolledUpPropertyCount](./Analytics.xml#L80:~:text=Number of properties in the entity instance that have been aggregated away +[DrillURL](./Analytics.xml#L86:~:text=URL to retrieve more detailed data related to a node of a recursive hierarchy. Annotations with this term MUST include a qualifier to select the hierarchy for which the drill URL is provided. +[PlanningAction](./Analytics.xml#L98:~:text=Processes or generates plan data. Its logic may have side-effects on entity sets. +[AggregatedProperties](./Analytics.xml#L106:~:text=Deprecated in favor of [`AggregatedProperty`](#AggregatedProperty) +[AggregatedProperty](./Analytics.xml#L124:~:text=Dynamic property for aggregate expression with specified aggregation method defined on the annotated entity type. +[AnalyticalContext](./Analytics.xml#L144:~:text=Collection of properties that define an analytical context +[LevelInformation](./Analytics.xml#L283:~:text=Information about grouping levels in the result set of an analytical request ## Functions -### [AutoExpand](./Analytics.xml#L179:~:text=Each element in the collection defines the property names for one level. A property must not referenced by more than one level. The first element in the collection defines the property names of the coarsest level, the following elements define the property names of consecutively finer-grained aggregation levels. All referenced properties must be groupable. -[ExpandLevel](./Analytics.xml#L196:~:text=The function result comprises the leveled hierarchy with the expanded levels and the following level as leaves in preorder. -[Aggregation](./Analytics.xml#L202:~:text=All properties in this collection must be custom aggregates. -[SiblingOrder](./Analytics.xml#L208:~:text=Each element in the collection defines the property names for one level. A property must not referenced by more than one level. The first element in the collection defines the property names of the coarsest level, the following elements define the property names of consecutively finer-grained aggregation levels. All referenced properties must be groupable. +[ExpandLevel](./Analytics.xml#L199:~:text=The function result comprises the leveled hierarchy with the expanded levels and the following level as leaves in preorder. +[Aggregation](./Analytics.xml#L205:~:text=All properties in this collection must be custom aggregates. +[SiblingOrder](./Analytics.xml#L211:~:text= -## [AggregatedPropertyType](./Analytics.xml#L124:~:text= -## [AnalyticalContextType](./Analytics.xml#L145:~:text=Allowed terms:
- [AggregatedProperty](#AggregatedProperty)
- [CustomAggregate](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Aggregation.V1.md#CustomAggregate) -[Dimension](./Analytics.xml#L159:~:text=Allowed terms:
- [AggregatedProperty](#AggregatedProperty)
- [CustomAggregate](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Aggregation.V1.md#CustomAggregate) +[Dimension](./Analytics.xml#L162:~:text= -## [AutoExpandLevel](./Analytics.xml#L247:~:text= -## [AutoExpandSiblingOrder](./Analytics.xml#L253:~:text= -## [SortOrder](./Analytics.xml#L262:~:text= + + + @@ -242,7 +245,9 @@ - + + + @@ -275,6 +280,12 @@ + + + + + + diff --git a/vocabularies/Hierarchy.json b/vocabularies/Hierarchy.json index b2035e65d..81631909f 100644 --- a/vocabularies/Hierarchy.json +++ b/vocabularies/Hierarchy.json @@ -33,8 +33,30 @@ "@Core.Description": "Hierarchy-specific information in the result set of a hierarchical request", "@Core.LongDescription": "The [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)\n governs what are the nodes and parents in the hierarchy, whereas this term defines derived information." }, + "HierarchyType": { + "$Kind": "ComplexType", + "@Common.Experimental": true, + "@Core.LongDescription": "The properties in this complex type contain information about\n an entry in the result set of a request with multiple grouping levels.", + "LimitedDescendantCount": { + "$Type": "Edm.Int64", + "$Nullable": true, + "@Core.Description": "Number of descendants a node has in the limited hierarchy" + }, + "DrillState": { + "$Nullable": true, + "@Core.Description": "Drill state of an occurrence of a node", + "@Core.LongDescription": "Possible drill states are:\n
- `expanded` if a node has children in the limited hierarchy\n
- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy\n
- `leaf` if a node has no children in the unlimited hierarchy" + }, + "DistanceFromRoot": { + "$Type": "Edm.Int64", + "$Nullable": true, + "@Core.Description": "Number of ancestors an occurrence of a node has in the limited hierarchy", + "@Core.LongDescription": "This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy." + } + }, "RecursiveHierarchyType": { "$Kind": "ComplexType", + "$BaseType": "Hierarchy.HierarchyType", "@Common.Experimental": true, "@Core.LongDescription": "The properties in this complex type contain information about\na node in the result set of a hierarchical request. If the same node occurs multiple times\nwith different parents, certain properties may differ between the occurrences.\nThe properties are derived when hierarchical transformations\nare applied whose first parameter has the annotated entity type\nand whose second parameter is the annotation qualifier.\n\nFor requests like\n```\nSalesOrganizations?$apply=\ndescendants(..., ID, filter(ID eq 'US'), keep start)\n/ancestors(..., ID, filter(contains(Name, 'New York')), keep start)\n/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)\n&$top=10\n```\nor\n```\nSalesOrganizations?$apply=groupby((rolluprecursive(..., ID,\n descendants(..., ID, filter(ID eq 'US')),\n ancestors(..., ID, filter(contains(Name, 'New York')), keep start))), aggregate(...))\n/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)\n&$top=10\n```\n(where `...,` stands for hierarchy nodes and hierarchy qualifier)\nthe following collections of hierarchy nodes are distinguished:\n\n|Collection|Definition|Value|Where in request|\n|----------|----------|-----|----------------|\n|sub-hierarchy|output set of a `descendants` transformation, possibly embedded in a `rolluprecursive` transformation, that is not preceded by an `ancestors` or `descendants` transformation|US sales organizations|rows 1–2|\n|matching nodes|see [`MatchCount`](#MatchCount)|US sales organizations with \"New York\" in their name|output set of `filter` transformation in row 3|\n|unlimited hierarchy|output set of the last `ancestors`, `descendants` or `traverse` transformation, possibly embedded in a `rolluprecursive` transformation, disregarding numeric fifth parameters|US sales organizations with leaves containing \"New York\"|rows 1–3|\n|limited hierarchy|output set of the last `ancestors`, `descendants`, `traverse` or [`Hierarchy.TopLevels`](#TopLevels) transformation, possibly embedded in a `rolluprecursive` transformation|2 levels of US sales organizations with leaves containing \"New York\"|rows 1–4|\n", "ExternalKey": { @@ -57,22 +79,6 @@ "$Nullable": true, "@Core.Description": "Number of descendants a node has in the unlimited hierarchy" }, - "LimitedDescendantCount": { - "$Type": "Edm.Int64", - "$Nullable": true, - "@Core.Description": "Number of descendants a node has in the limited hierarchy" - }, - "DrillState": { - "$Nullable": true, - "@Core.Description": "Drill state of an occurrence of a node", - "@Core.LongDescription": "Possible drill states are:\n
- `expanded` if a node has children in the limited hierarchy\n
- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy\n
- `leaf` if a node has no children in the unlimited hierarchy" - }, - "DistanceFromRoot": { - "$Type": "Edm.Int64", - "$Nullable": true, - "@Core.Description": "Number of ancestors an occurrence of a node has in the limited hierarchy", - "@Core.LongDescription": "This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy." - }, "LimitedRank": { "$Type": "Edm.Int64", "$Nullable": true, diff --git a/vocabularies/Hierarchy.md b/vocabularies/Hierarchy.md index b092ab032..2c05d7133 100644 --- a/vocabularies/Hierarchy.md +++ b/vocabularies/Hierarchy.md @@ -9,26 +9,26 @@ Terms for Hierarchies Term|Type|Description :---|:---|:---------- [RecursiveHierarchy](./Hierarchy.xml#L41:~:text=Hierarchy-specific information in the result set of a hierarchical request
The [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy) governs what are the nodes and parents in the hierarchy, whereas this term defines derived information. -[RecursiveHierarchyActions](./Hierarchy.xml#L154:~:text=Actions for maintaining the recursive hierarchy defined by the [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)
When an annotation with this term is present, the [`ParentNavigationProperty`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchyType) in the base term must not have a collection-valued segment prior to its last segment. -[MatchCount](./Hierarchy.xml#L186:~:text=Instance annotation on the result of an `$apply` query option containing the number of matching nodes after hierarchical transformations
The service MAY designate a subset of the `$apply` result as "matching nodes". For requests following the pattern described [here](#RecursiveHierarchyType), this subset is the output set of the `filter` or `search` transformation that occurs as the fourth parameter of the last `ancestors` transformation or occurs nested into it.
For requests not following this pattern, the subset NEED NOT be defined.
This instance annotation is available if [`RecursiveHierarchy/Matched`](#RecursiveHierarchyType) and [`RecursiveHierarchy/MatchedDescendantCount`](#RecursiveHierarchyType) are also available. -[RecursiveHierarchySupported](./Hierarchy.xml#L268:~:text=Whether the annotated collection acts as a [`RecursiveHierarchy`](#RecursiveHierarchy) with the given qualifier
This tag is applied to a collection with the same qualifier as the [`RecursiveHierarchy`](#RecursiveHierarchy) term which is applied to its entity type. The recursive hierarchy can then only be addressed through a collection where this tag is true. +[RecursiveHierarchyActions](./Hierarchy.xml#L161:~:text=Actions for maintaining the recursive hierarchy defined by the [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)
When an annotation with this term is present, the [`ParentNavigationProperty`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchyType) in the base term must not have a collection-valued segment prior to its last segment. +[MatchCount](./Hierarchy.xml#L193:~:text=Instance annotation on the result of an `$apply` query option containing the number of matching nodes after hierarchical transformations
The service MAY designate a subset of the `$apply` result as "matching nodes". For requests following the pattern described [here](#RecursiveHierarchyType), this subset is the output set of the `filter` or `search` transformation that occurs as the fourth parameter of the last `ancestors` transformation or occurs nested into it.
For requests not following this pattern, the subset NEED NOT be defined.
This instance annotation is available if [`RecursiveHierarchy/Matched`](#RecursiveHierarchyType) and [`RecursiveHierarchy/MatchedDescendantCount`](#RecursiveHierarchyType) are also available. +[RecursiveHierarchySupported](./Hierarchy.xml#L275:~:text=Whether the annotated collection acts as a [`RecursiveHierarchy`](#RecursiveHierarchy) with the given qualifier
This tag is applied to a collection with the same qualifier as the [`RecursiveHierarchy`](#RecursiveHierarchy) term which is applied to its entity type. The recursive hierarchy can then only be addressed through a collection where this tag is true. ## Actions -### [Template_ChangeNextSiblingAction](./Hierarchy.xml#L278:~:text=This parameter has properties with the same names as the key properties of the entity type. next(T) = S after the action. If R is a node with next(R) = S before the action, then next(R) = T after the action, even if S = null. It is an error if S has a different parent than T. +**[Node](./Hierarchy.xml#L288:~:text=This parameter has properties with the same names as the key properties of the entity type. next(T) = S after the action. If R is a node with next(R) = S before the action, then next(R) = T after the action, even if S = null. It is an error if S has a different parent than T. -### [Template_CopyAction](./Hierarchy.xml#L312:~:text= -### [TopLevels](./Hierarchy.xml#L214:~:text= +## [HierarchyType](./Hierarchy.xml#L50:~:text=Possible drill states are:
- `expanded` if a node has children in the limited hierarchy
- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy
- `leaf` if a node has no children in the unlimited hierarchy +[DistanceFromRoot](./Hierarchy.xml#L68:~:text=This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy. + -## [RecursiveHierarchyType](./Hierarchy.xml#L50:~:text=If a `NodeType` exists, the external key is unique only in combination with it. Or the external key can coincide with the [`Aggregation.RecursiveHierarchy/NodeProperty`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchyType). -[NodeType](./Hierarchy.xml#L94:~:text=In a recursive hierarchy with mixed types, nodes can
- have a type-specific (navigation) property whose name is the node type or
- be represented by entities of different subtypes of a common entity type that is annotated with the `RecursiveHierarchy` annotation. The qualified name of the subtype is the node type. -[ChildCount](./Hierarchy.xml#L103:~:text=Possible drill states are:
- `expanded` if a node has children in the limited hierarchy
- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy
- `leaf` if a node has no children in the unlimited hierarchy -[DistanceFromRoot](./Hierarchy.xml#L121:~:text=This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy. -[LimitedRank](./Hierarchy.xml#L127:~:text=The rank of a node is the index of the node in the sequence of nodes created from a preorder or postorder traversal of the limited hierarchy. The first node in the traversal has rank 0. -[SiblingRank](./Hierarchy.xml#L134:~:text=The sibling rank of a node is the index of the node in the sequence of all nodes in the unlimited hierarchy with the same parent. The first sibling has rank 0. -[Matched](./Hierarchy.xml#L141:~:text=Possible drill states are:
- `expanded` if a node has children in the limited hierarchy
- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy
- `leaf` if a node has no children in the unlimited hierarchy +[*DistanceFromRoot*](./Hierarchy.xml#L68:~:text=This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy. +[ExternalKey](./Hierarchy.xml#L112:~:text=If a `NodeType` exists, the external key is unique only in combination with it. Or the external key can coincide with the [`Aggregation.RecursiveHierarchy/NodeProperty`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchyType). +[NodeType](./Hierarchy.xml#L119:~:text=In a recursive hierarchy with mixed types, nodes can
- have a type-specific (navigation) property whose name is the node type or
- be represented by entities of different subtypes of a common entity type that is annotated with the `RecursiveHierarchy` annotation. The qualified name of the subtype is the node type. +[ChildCount](./Hierarchy.xml#L128:~:text=The rank of a node is the index of the node in the sequence of nodes created from a preorder or postorder traversal of the limited hierarchy. The first node in the traversal has rank 0. +[SiblingRank](./Hierarchy.xml#L141:~:text=The sibling rank of a node is the index of the node in the sequence of all nodes in the unlimited hierarchy with the same parent. The first sibling has rank 0. +[Matched](./Hierarchy.xml#L148:~:text= -## [RecursiveHierarchyActionsType](./Hierarchy.xml#L162:~:text= -## [TopLevelsExpandType](./Hierarchy.xml#L257:~:text= - + + + + The properties in this complex type contain information about + an entry in the result set of a request with multiple grouping levels. + + + + + + + + Possible drill states are: + <br>- `expanded` if a node has children in the limited hierarchy + <br>- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy + <br>- `leaf` if a node has no children in the unlimited hierarchy + + + + + + This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy. + + + + The properties in this complex type contain information about @@ -106,24 +131,6 @@ the following collections of hierarchy nodes are distinguished: - - - - - - - Possible drill states are: - <br>- `expanded` if a node has children in the limited hierarchy - <br>- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy - <br>- `leaf` if a node has no children in the unlimited hierarchy - - - - - - This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy. - -