Namespace: com.sap.vocabularies.Hierarchy.v1
Terms for Hierarchies
| Term | Type | Description |
|---|---|---|
| RecursiveHierarchy (Experimental) | RecursiveHierarchyType | Hierarchy-specific information in the result set of a hierarchical request The base term governs what are the nodes and parents in the hierarchy, whereas this term defines derived information. |
| RecursiveHierarchyActions (Experimental) | RecursiveHierarchyActionsType | Actions for maintaining the recursive hierarchy defined by the base term When an annotation with this term is present, the ParentNavigationProperty in the base term must not have a collection-valued segment prior to its last segment. |
| MatchCount (Experimental) | Int64 | Instance annotation on the result of an $apply query option containing the number of matching nodes after hierarchical transformationsThe service MAY designate a subset of the $apply result as "matching nodes". For requests following the pattern described here, 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 and RecursiveHierarchy/MatchedDescendantCount are also available. |
| RecursiveHierarchySupported (Experimental) | Tag | Whether the annotated collection acts as a RecursiveHierarchy with the given qualifierThis tag is applied to a collection with the same qualifier as the 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. |
Template for actions that move a node among its siblings and are named in RecursiveHierarchyActions/ChangeNextSiblingAction
| Parameter | Type | Description |
|---|---|---|
| Node | EntityType | Binding parameter: The node T to be moved |
| NextSibling | ComplexType? | Key of the node's new next sibling S (null if the node shall become the last sibling) 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 for actions that copy a node and its descendants and are named in RecursiveHierarchyActions/CopyAction
To give the copied sub-hierarchy a parent, the action invocation can be followed
by a PATCH that binds the parent navigation property (for example, Superordinate in the following JSON batch request).
{"requests": [{
"id": "1",
"method": "post",
"url": "HierarchyDirectory(1)/Nodes('A')/CopyAction"
}, {
"id": "2",
"dependsOn": ["1"],
"method": "patch",
"url": "$1",
"body": {
"Superordinate@odata.bind": "Nodes('B')"
}
}]}| Parameter | Type | Description |
|---|---|---|
| Node | EntityType | Binding parameter: The node to be copied |
| → | EntityType | The copied node |
Returns the first n levels of a hierarchical collection in preorder with individual nodes expanded or collapsed
This function can be used as a transformation whose input set has a recursive hierarchy
defined by an Aggregation.RecursiveHierarchy
annotation on the entity type of the HierarchyNodes.
(Its binding parameter is the unlimited hierarchy as defined here,
its output is the limited hierarchy.) The output initially contains the nodes with less than n ancestors
in the hierarchical collection given in the binding parameter.
Then individual nodes are expanded, shown or collapsed in the output, which extends or reduces the limited hierarchy.
Finally the output is sorted in preorder as with the traverse transformation with the hierarchy-specific
definition of start nodes.
| Parameter | Type | Description |
|---|---|---|
| InputSet | [EntityType] | Binding parameter |
| HierarchyNodes | [EntityType] | A collection, given through a $root expression |
| HierarchyQualifier | HierarchyQualifier | |
| NodeProperty | String | Property path to the node identifier, evaluated relative to the binding parameter |
| Levels | Int64 | Optional parameter: The number n of levels to be output, absent means all levels |
| Show | [String] | Optional parameter: Identifiers of nodes to be shown |
| ExpandLevels | [TopLevelsExpandType] | Optional parameter: Nodes to be expanded |
| → | [EntityType] |
The properties in this complex type contain information about a node in the result set of a hierarchical request. If the same node occurs multiple times with different parents, certain properties may differ between the occurrences. The properties are derived when hierarchical transformations are applied whose first parameter has the annotated entity type and whose second parameter is the annotation qualifier.
For requests like
SalesOrganizations?$apply=
descendants(..., ID, filter(ID eq 'US'), keep start)
/ancestors(..., ID, filter(contains(Name, 'New York')), keep start)
/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)
&$top=10
or
SalesOrganizations?$apply=groupby((rolluprecursive(..., ID,
descendants(..., ID, filter(ID eq 'US')),
ancestors(..., ID, filter(contains(Name, 'New York')), keep start))), aggregate(...))
/Hierarchy.TopLevels(..., NodeProperty='ID', Levels=2)
&$top=10
(where ..., stands for hierarchy nodes and hierarchy qualifier)
the following collections of hierarchy nodes are distinguished:
| Collection | Definition | Value | Where in request |
|---|---|---|---|
| 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 |
| matching nodes | see MatchCount |
US sales organizations with "New York" in their name | output set of filter transformation in row 3 |
| 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 |
| limited hierarchy | output set of the last ancestors, descendants, traverse or Hierarchy.TopLevels transformation, possibly embedded in a rolluprecursive transformation |
2 levels of US sales organizations with leaves containing "New York" | rows 1–4 |
| Property | Type | Description |
|---|---|---|
| ExternalKey | String? | Human-readable key value for a node 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. |
| NodeType | String? | Type of a node In a recursive hierarchy with mixed types, nodes can
annotated with the |
| ChildCount | Int64? | Number of children a node has in the unlimited hierarchy |
| DescendantCount | Int64? | Number of descendants a node has in the unlimited hierarchy |
| LimitedDescendantCount | Int64? | Number of descendants a node has in the limited hierarchy |
| DrillState | String? | Drill state of an occurrence of a node 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 | Int64? | Number of ancestors an occurrence of a node has in the limited hierarchy This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy. |
| LimitedRank | Int64? | Rank of a node in the limited hierarchy in preorder or postorder 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 | Int64? | Sibling rank of a node 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 | Boolean? | Flag indicating matching nodes |
| MatchedDescendantCount | Int64? | Number of matching descendants a node has in the unlimited hierarchy |
The qualified action names identify actions for maintaining nodes in the recursive hierarchy,
which are specific for the given annotation qualifier.
These actions MUST have the same signature as the template actions linked below, with
Edm.EntityType replaced with the entity type on which the recursive hierarchy is defined.
The resource path of the binding parameter MUST traverse the hierarchy collection,
including any hierarchy directory. If the resource path contains a Content ID reference to an earlier request,
the hierarchy directory MUST be determined from the resource path of that request.
{"requests": [{
"id": "1",
"method": "post",
"url": "HierarchyDirectory(1)/Nodes",
"body": {
"Name": "child of A",
"Superordinate@odata.bind": "Nodes('A')"
}
}, {
"id": "2",
"dependsOn": ["1"],
"method": "post",
"url": "$1/Hierarchy.ChangeNextSiblingAction",
"body": {
"NextSibling": null
}
}]}The template actions themselves cannot be invoked.
| Property | Type | Description |
|---|---|---|
| ChangeNextSiblingAction | QualifiedName? | Action that moves a node among its siblings, following this template |
| ChangeSiblingForRootsSupported | Boolean | Whether the sibling of a root can be changed |
| CopyAction | QualifiedName? | Action that copies a node and its descendants, following this template |
Information about nodes to be expanded
| Property | Type | Description |
|---|---|---|
| NodeID | String | Identifier of a node to be expanded |
| Levels | Int64? | Number of levels to be expanded, null means all levels, 0 means collapsed |