ABAP Keyword Documentation → ABAP - Dictionary → ABAP CDS in ABAP Dictionary → ABAP CDS - Data Definitions → ABAP CDS - DDL for Data Definitions
ABAP CDS - DEFINE HIERARCHY
Other versions:
7.31 | 7.40 | 7.54
Syntax
[@entity_annot1]
[@entity_annot2]
...
[@hierarchy_annot1]
[@hierarchy_annot2]
...
[DEFINE] HIERARCHY cds_entity
[parameter_list]
AS PARENT CHILD HIERARCHY(
SOURCE cds_view
CHILD TO PARENT ASSOCIATION _hierarchy_assoc
[PERIOD FROM field1 TO field2 VALID FROM from TO to]
[DIRECTORY _directory_assoc FILTER BY cond_expr]
[START WHERE cond_expr]
SIBLINGS ORDER BY field1 [ASCENDING|DESCENDING][,
field2 [ASCENDING|DESCENDING], ...]
[DEPTH depth]
[NODETYPE node_type]
[MULTIPLE PARENTS {NOT ALLOWED}|LEAVES|ALLOWED]
[ORPHANS IGNORE|ERROR|ROOT]
[CYCLES ERROR|BREAKUP]
[GENERATE SPANTREE] )
{ element_list }
Extras
1. ... SOURCE cds_view
2. ... CHILD TO PARENT ASSOCIATION _hierarchy_assoc
3. ... PERIOD FROM field1 TO field2 VALID FROM from TO to
4. ... DIRECTORY _directory_assoc FILTER BY cond_expr
5. ... START WHERE cond_expr
6. ... SIBLINGS ORDER BY field1 [ASCENDING|DESCENDING], ...
7. ... DEPTH depth
8. ... NODETYPE node_type
9. ... MULTIPLE PARENTS {NOT ALLOWED}|{LEAVES ONLY}|ALLOWED
10. ... ORPHANS IGNORE|ERROR|ROOT
11. ... CYCLES ERROR|BREAKUP
12. ... GENERATE SPANTREE
Effect
Defines a CDS entity cds_entity as a CDS hierarchy in the CDS DDL. A CDS hierarchy has a tabular results set whose rows construct parent-child relationships. When a CDS hierarchy is accessed as the data source of a ABAP SQL query, it is handled like a hierarchy in which additional hierarchy columns can be selected.
- @entity_annot and @hierarchy_annot can be used to specify optional annotations for the CDS hierarchy.
- parameter_list is used to declare a list of optional input parameters for the CDS hierarchy.
- element_list is used to declare the elements of the CDS hierarchy.
The additions in parentheses after AS PARENT CHILD HIERARCHY define the way the hierarchy is created:
- SOURCE must be followed by a CDS view cds_view as the source of the hierarchy.
- CHILD TO PARENT ASSOCIATION must be followed by a hierarchy association _hierarchy_assoc published by the source cds_view. The source data source and target data source of this association must be the source cds_view. The ON condition of the hierarchy association defines the parent-child relationships between the hierarchy nodes.
- START WHERE can be followed by a start condition that defines root nodes for the root node set of the hierarchy. The hierarchy consists of the root nodes of the root node set and their descendant nodes. If START WHERE is not specified, the root node set consists of all parent nodes that contain its initial value.
All other additions define further properties of the hierarchy. The rows of the tabular results set of the CDS hierarchy are the hierarchy nodes of the new hierarchy but without its hierarchy columns.
Notes
- The syntax and functions of a CDS hierarchy overlap to a large extent with the
hierarchy
generator
HIERARCHY
in ABAP SQL
- Unlike in ABAP SQL, however, ABAP CDS cannot access the additional hierarchy columns of a CDS hierarchy. Instead, the associated hierarchy attributes must be entered in the element list of the CDS hierarchy if required.
- On SAP HANA databases,
the results sets of CDS hierarchies plus the hierarchy generator
HIERARCHY
are created by using the SAP HANA hierarchy generator function HIERARCHY and similar. More information can be found in the documentation.
Example
Defines a simple CDS hierarchy. The program DEMO_HIERARCHY_TREE accesses the CDS hierarchy and compares this with accesses to similar hierarchies in ABAP SQL.
with parameters
p_id : abap.int4
as parent child hierarchy(
source
DEMO_CDS_SIMPLE_TREE_SOURCE
child to parent association _tree
start where
id = :p_id
siblings order by
id ascending
)
{
id,
parent,
name
}
Addition 1
... SOURCE cds_view
Effect
The mandatory addition SOURCE specifies a CDS view as a source of the CDS hierarchy. This source must publish the hierarchy association specified after CHILD TO PARENT ASSOCIATION in its SELECT list.
Note
CDS views are currently the only CDS entities that can be specified as the source of a CDS hierarchy. More specifically, a CDS hierarchy cannot be the source of another CDS hierarchy.
Example
The CDS hierarchy of the previous example uses the following CDS view as a source:
@AccessControl.authorizationCheck: #NOT_REQUIRED
define view DEMO_CDS_SIMPLE_TREE_SOURCE
as select from
demo_simple_tree
association [1..1] to DEMO_CDS_SIMPLE_TREE_SOURCE as _tree on
$projection.parent = _tree.id
{
_tree,
id,
parent_id as parent,
name
}
Addition 2
... CHILD TO PARENT ASSOCIATION _hierarchy_assoc
Effect
The mandatory addition CHILD TO PARENT ASSOCIATION specifies the hierarchy association whose ON condition selects the descendant nodes of the root node set. The hierarchy association must be published by the CDS view specified after SOURCE.
The hierarchy association defines the parent-child relationship between the hierarchy nodes. The following conditions apply here:
- The CDS association must be a self-association.
- Only equality comparisons with the operator = and joined using AND can occur in the ON condition of the CDS association.
- In each comparison in the ON condition, one field of the source data source must be compared with a field (prefixed with _hierarchy_assoc) of the target data source.
- The source data source of the CDS association cannot contain any fields that have the same name as a hierarchy attribute. An alternative element name must be defined for these fields.
Each row of the results set of the source hierarchy_source that meets the ON condition for an existing hierarchy node is included recursively in the hierarchy as its child node (if this is possible).
Note
The optional additions define further conditions specifying whether a row can be included as a hierarchy node or not.
Example
The CDS view of the previous example publishes its association _tree. This CDS association meets all requirements of a hierarchy association and can be used as one.
Addition 3
... PERIOD FROM field1 TO field2 VALID FROM from TO to
Effect
The optional addition PERIOD defines the hierarchy as a temporal hierarchy in which the hierarchy nodes are limited by an adjustment of time intervals.
- field1 and field2 are used to specify the fields of the source cds_view that define the lower and upper limits of a period in the hierarchy data. field1 and field2 must be different fields of the same data type. This can be:
- The built-in type DATS of ABAP Dictionary.
- A data type that is defined by one of the data elements TIMESTAMP or TIMESTAMPL.
- from and to define the lower and upper limit of a time interval that acts as a condition for the periods of the root node set. The data type of from and to must match the data type of field1 and field2. The following can be specified:
- Parameters from the parameter list of the hierarchy. Here, only the syntax $parameters.pname is possible, and not :pname.
- Character literals whose value matches the requested data type.
A temporal hierarchy is created as follows:
- Only root nodes of the root node set in which the period defined using field1 and field2 has a non empty intersection with the time interval defined by from and to are taken into account. This intersection forms the validity interval of the root node.
- Only child nodes in which the period defined by field1 and field2 has a non empty intersection with the validity interval of the parent node are generated. This intersection forms the validity interval of the child node.
For temporal hierarchies, there are additional hierarchy attributes VALID_FROM and VALID_UNTIL that contain the interval limits of the validity interval of each hierarchy node.
The addition PERIOD must not be used with GENERATE SPANTREE.
Notes
- The validity interval of a descendant node is always a subset of a validity interval of all ancestor nodes. Validity intervals can only remain the same or become narrower from hierarchy level to hierarchy level, they can never get wider.
- For a descendant node to belong to a temporal hierarchy, it is not sufficient for its period to overlap with the time interval defined by from and to. Only the validity interval of the parent node is decisive. A path of a normal hierarchy is truncated in a temporal hierarchy at the position in which there is no intersection between the period and the preceding validity interval.
- The source data source of the current hierarchy association must not have any fields called VALID_FROM or VALID_UNTIL. An alternative element name must be defined for these fields.
- The value of to can also be less than the value of from. However, a validity interval is formed where necessary. In contrast, if the value of the lower interval limit of the period is greater than the value of the upper interval limit, the validity interval is empty.
- Additions such as MULTIPLE PARENTS or CYCLES affect the temporal hierarchy. Nodes that would raise an exception in a normal hierarchy can be hidden in a temporal hierarchy.
- To generate a temporal hierarchy, in an SAP HANA database, the hierarchy generator function HIERARCHY_TEMPORAL there is called.
Example
The following CDS hierarchies create two temporal
hierarchies. Here, date fields and time stamp fields are both used once as
periodes. The program DEMO_HIERARCHY_TEMPORAL accesses the CDS hierarchies and compares the results with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar
way. When executed, this program demonstrates how the addition PERIOD works.
with parameters
p_date_from : dats,
p_date_to : dats
as parent child hierarchy(
source DEMO_CDS_PARENT_CHILD_SRC_PRD
child to parent association _relat
period from date_from to date_to
valid from $parameters.p_date_from
to $parameters.p_date_to
start where
id = 'A'
siblings order by
id
)
{
id,
parent,
$node.valid_from as h_valid_from,
$node.valid_until as h_valid_until }
with parameters
p_ts_from : timestamp,
p_ts_to : timestamp
as parent child hierarchy(
source DEMO_CDS_PARENT_CHILD_SRC_PRD
child to parent association _relat
period from ts_from to ts_to
valid from $parameters.p_ts_from
to $parameters.p_ts_to
start where
id = 'A'
siblings order by
id
)
{
id,
parent,
$node.valid_from as h_valid_from,
$node.valid_until as h_valid_until }
Addition 4
... DIRECTORY _directory_assoc FILTER BY cond_expr
Effect
The optional addition DIRECTORY defines a filter condition cond_expr for the rows of the source of the hierarchy specified after SOURCE. The hierarchy is generated only from those rows in the source that meet the filter condition. AND comparisons for equality can be specified for cond_expr using =:
- The operator on the left side of a comparison must be an element of the current hierarchy whose name occurs as an operand in the CDS view specified after SOURCE as follows:
- On the left side of an ON condition of a CDS association _directory_assoc.
- On the left side of an ON condition of the hierarchy association _hierarchy_assoc.
- The operator on the right side of the comparison can be a simple literal or a type-friendly parameter from the parameter list of the hierarchy.
The same rules apply to the comparable types as to CDS views.
Notes
- A filter condition removes all hierarchy nodes and their descendant nodes from the results set that do not match the condition cond_exp.
- The content of the target data source of the CDS association _directory_assoc is ignored when the filter condition is evaluated.
- The restriction of the operands on the left side of a comparison to the operands of a CDS association of the source is supported by certain programming models. Any frameworks that are based on these models read data from the target data source of this CDS association and pass it to input parameters of the hierarchy that evaluates them in the filter condition.
Example
The following CDS view defines a self association _pcr, which itself defines a parent-child relationship, and a CDS association _dir of a database table DEMO_HIERA_DIR:
@AccessControl.authorizationCheck: #NOT_REQUIRED
define view DEMO_CDS_PARENT_CHILD_SRC_DIR
as select from
demo_parchld_dir
association [1..*] to DEMO_CDS_PARENT_CHILD_SRC_DIR as _pcr on
$projection.parent = _pcr.id and
$projection.dir_entry = _pcr.id
association [1..*] to demo_hiera_dir as _dir on
$projection.dir_entry = _dir.dir_entry
{
_pcr,
_dir,
id,
parent_id as parent,
dir_entry
}
The following CDS hierarchy uses the operand dir_entry from the left side of the ON condition from the CDS view in the filter condition after DIRECTORY _dir FILTER BY:
with parameters
p_id1 : abap.char(2),
p_id2 : abap.char(2),
p_dir : abap.char(2)
as parent child hierarchy(
source
DEMO_CDS_PARENT_CHILD_SRC_DIR
child to parent association _pcr
directory _dir filter by dir_entry = :p_dir
start where
id = :p_id1 or id = :p_id2
siblings order by
parent
multiple parents allowed
)
{
id,
parent,
dir_entry
}
When the program DEMO_HIERARCHY_PARENTCHILD_DIR is executed, various parameters can be passed and the filter condition is demonstrated.
Addition 5
... START WHERE cond_expr
Effect
The optional addition START WHERE specifies the start condition for creating the hierarchy. START WHERE can be followed by a logical expression cond_expr that selects rows from the source cds_view. The same operators can be specified for cond_expr as in a WHERE clause of a CDS view and the same rules apply. The operands on the left side can be elements of the CDS view specified after SOURCE. The operands on the right side can be literals, parameters from the parameter list of the hierarchy, and session variables. When specifying literals, parameters, and session variables, the same applies as when defining CDS views.
If the addition START WHERE is not specified explicitly, it is added implicitly with a condition that checks the parent node defined in the hierarchy association in question for its initial value.
The selected rows are inserted in the hierarchy as a root node set. For each root node in the root node set, the descendant nodes are selected that meet the ON condition of the hierarchy association and, if possible, inserted in the hierarchy.
Notes
- It is advisable to always specify the start condition explicitly, since this makes the definition clearer. Furthermore, the root node set defined by the implicit start condition is not always suitable and also cannot be modified using parameters.
- The start condition should select a feasible set of root nodes. If no rows in the results set of the source cds_view meet the condition, the hierarchy is empty. If all rows meet the condition, the descendant nodes of every row are selected and inserted.
Example
The following CDS hierarchy uses an interval boundary with BETWEEN as
a start condition. The program DEMO_HIERARCHY_START_WHERE accesses the CDS hierarchy and compares the result with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar way. When executed, this program demonstrates how this addition works.
with parameters
p_from : abap.char(2),
p_to : abap.char(2)
as parent child hierarchy(
source
DEMO_CDS_PARENT_CHILD_SOURCE
child to parent association _relat
start where
id between :p_from and :p_to
siblings order by
id
multiple parents allowed
cycles breakup
)
{
id,
parent
}
Addition 6
... SIBLINGS ORDER BY field1 [ASCENDING|DESCENDING], ...
Effect
The mandatory addition SIBLINGS ORDER BY sorts sibling nodes in the hierarchy. Fields field1, field2, ... of the source cds_view can be specified in a comma-separated list after the addition SIBLINGS ORDER BY to specify the order of the sibling nodes.
The addition ASCENDING or DESCENDING can be specified for each field to specify an ascending or descending order (ascending is the default).
The fields specified after SIBLINGS ORDER BY cannot be of the type LCHR, LRAW, STRING, RAWSTRING, or GEOM_EWKB.
Note
The addition SIBLINGS ORDER BY is mandatory in the case of CDS hierarchies, since this sort cannot be performed at a later time. For example, the result of a hierarchy navigator in ABAP SQL may depend on how the hierarchy specified as a source is sorted. A hierarchy generator specified as a source can be sorted directly here, but this is no longer possible in the case of predefined CDS hierarchies.
Example
The following CDS hierarchy sorts siblings in descending order by the field id.
The program DEMO_HIERARCHY_SIBLINGS_ORDER accesses the CDS hierarchy and compares the result with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar way. When executed, this program demonstrates how this addition works.
with parameters
p_id : abap.int4
as parent child hierarchy(
source
DEMO_CDS_SIMPLE_TREE_SOURCE
child to parent association _tree
start where
id = :p_id
siblings order by
id descending
)
{
id,
parent,
name
}
Addition 7
... DEPTH depth
Effect
The optional addition depth limits the number of hierarchy levels used to create descendant nodes. depth can be a simple literal or a parameter from the parameter list of the hierarchy that has an integer type.
The value in depth has the following meaning:
- For depth values greater then 0, the number of hierarchy edges are traversed that is specified in depth, starting from a root node.
- If the value of depth is 0, only the root nodes are inserted in the hierarchy.
- For depth values less than 0, no hierarchy nodes are created.
The addition DEPTH can be used only if the addition ORPHANS is not specified or is specified as ORPHANS IGNORE.
Example
The following CDS hierarchy uses an input parameter p_depth to restrict
the hierarchy levels. The program DEMO_HIERARCHY_DEPTH accesses the CDS hierarchy and compares the result with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar way. When executed, this program demonstrates how this addition works.
with parameters
p_depth : abap.int4
as parent child hierarchy(
source
DEMO_CDS_SIMPLE_TREE_SOURCE
child to parent association _tree
start where
id = 1
siblings order by
id ascending
depth :p_depth
)
{
name,
$node.hierarchy_level as hiera_level
}
Addition 8
... NODETYPE node_type
Effect
The optional addition NODETYPE defines an element of the hierarchy as a node type. An element of the element list can be specified for node_type. This information is saved in the metadata of the CDS hierarchy and can be read by consumers using an API.
Notes
- An element defined as a node type can be used to stress semantic differences in technically similar hierarchy nodes.
- The API for reading the properties of a CDS hierarchy is not yet available.
Example
The following tree-like CDS hierarchy defines the element name as a node type. If a hierarchy node in the element name has the value Apple, it is a leaf node without any descendant nodes. The program DEMO_HIERARCHY_TREE_NODETYPE accesses the CDS hierarchy and when executed returns any hierarchy nodes that break the rule.
as parent child hierarchy(
source
DEMO_CDS_SIMPLE_TREE_SOURCE
child to parent association _tree
start where
id = 1
siblings order by
id ascending
nodetype name
)
{
id,
parent,
name
}
Addition 9
... MULTIPLE PARENTS {NOT ALLOWED}|{LEAVES ONLY}|ALLOWED
Effect
The optional addition MULTIPLE PARENTS specifies whether the hierarchy can have child nodes with multiple parent nodes:
- NOT ALLOWED
- LEAVES ONLY
- ALLOWED
Example
The following CDS hierarchy allows multiple parent nodes for leaf nodes. The program DEMO_HIERARCHY_MULTI_PARENTS accesses the CDS hierarchy and compares the result with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar way. When executed, this program demonstrates how this addition works.
as parent child hierarchy(
source
DEMO_CDS_PARENT_CHILD_SOURCE
child to parent association _relat
start where
id = 'A'
siblings order by
id
multiple parents leaves
)
{
id,
parent,
$node.hierarchy_level as hiera_level
}
Addition 10
... ORPHANS IGNORE|ERROR|ROOT
Effect
The optional addition ORPHANS defines the way orphan nodes are handled. The following categories of orphan nodes exist:
- Hierarchy nodes that could have parent nodes (as specified by the parent-child relationship) but the parent nodes are not in the hierarchy (known as true orphans).
- Hierarchy nodes that cannot be reached from the root node set using hierarchy edges.
- Hierarchy nodes that are part of a node cycle and cannot be reached from the root node set using hierarchy nodes (known as island orphans).
The additions work as follows:
- IGNORE
- ERROR
- ROOT
- True orphans are included in the root node set as root nodes and flagged as orphan nodes in the hierarchy attribute HIERARCHY_IS_ORPHAN.
- Descendant nodes of true orphans are handled like descendant nodes of parent nodes from the root node set, but are also flagged as orphan nodes in the hierarchy attribute HIERARCHY_IS_ORPHAN.
- For the hierarchy nodes of island orphans, a parent node in the root node set is generated for the child node where the cycle occurs. In the generated root node, all columns of the source hierarchy_source contain the null value. In the hierarchy attributes, the additional root node is flagged as an orphan node and PARENT_ID also contains the null value.
Example
The following CDS hierarchy transforms orphan nodes into root nodes. The program DEMO_HIERARCHY_ORPHANS accesses the CDS hierarchy and compares the result with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar way. When executed, this program demonstrates how this addition works.
as parent child hierarchy(
source
DEMO_CDS_PARENT_CHILD_SOURCE
child to parent association _relat
start where
id = 'A'
siblings order by
id
multiple parents allowed
orphans root
cycles breakup
)
{
id,
parent,
$node.node_id as hiera_node_id,
$node.parent_id as hiera_parent_id,
$node.hierarchy_is_orphan as hiera_is_orphan,
$node.hierarchy_is_cycle as hiera_is_cycle,
$node.hierarchy_rank as hiera_rank,
$node.hierarchy_parent_rank as hiera_parent_rank,
$node.hierarchy_level as hiera_level
}
Addition 11
... CYCLES ERROR|BREAKUP
Effect
The addition CYCLES defines how node cycles are defined. The additions work as follows:
- ERROR
- BREAKUP
If the addition BREAKUP is specified, MULTIPLE PARENTS ALLOWED must also be specified.
Example
The following CDS hierarchy breaks node cycles using CYCLES BREAKUP. The program DEMO_HIERARCHY_CYCLES accesses the CDS hierarchy and compares the result with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar way. When executed, this program demonstrates how this addition works.
as parent child hierarchy(
source
DEMO_CDS_PARENT_CHILD_SOURCE
child to parent association _relat
start where
id = 'A'
or id = 'X'
or id = 'Y'
or id = 'Z'
siblings order by
id
multiple parents allowed
cycles breakup
)
{
id,
parent,
$node.hierarchy_is_cycle as hiera_is_cycle,
$node.hierarchy_level as hiera_level
}
Addition 12
... GENERATE SPANTREE
Effect
If the addition GENERATE SPANTREE is specified, only those child nodes without multiple parent nodes are inserted in the hierarchy, starting from every root node. If, due to its parent-child relationships, a child node were to have multiple parent nodes after its root node, precisely one of the potential paths from the root node to this child node is selected and the child node is created for this path only.
- If the paths have different lengths, the shortest is selected.
- If the paths all have the same length, the first path found is selected.
If the addition GENERATE SPANTREE is specified, the additions MULTIPLE PARENTS, ORPHANS, and CYCLES cannot be specified and other defaults apply in parts:
- MULTIPLE PARENTS is used implicitly with ALLOWED.
- CYCLES is used implicitly with BREAKUP.
Notes
- If the parent-child relationships for the current data do not produce tree-like hierarchies, the addition GENERATE SPANTREE is ignored.
- Even if one path (from many paths) to a child node is selected, this does not mean that all others are rejected. In this case, only the edges leading to the child node are missing.
- The addition GENERATE SPANTREE can be used to detect whether at least one path leads from a root node to a child node without the results set needing to contain all paths.
- The addition GENERATE SPANTREE is used in an SAP HANA database to access the hierarchy generator function HIERARCHY_SPANTREE there.
Example
The following CDS hierarchy uses the addition GENERATE SPANTREE. The program DEMO_HIERARCHY_SPANTREE accesses the CDS hierarchy and compares the result with the
hierarchy generator HIERARCHY
in
ABAP SQL used in a similar way. When executed, this program demonstrates how this addition works.
as parent child hierarchy(
source
DEMO_CDS_PARENT_CHILD_SOURCE
child to parent association _relat
start where
id = 'A'
or id = 'K'
or id = 'X'
or id = 'Y'
siblings order by
id
generate spantree
)
{
id,
parent
}
Continue
ABAP CDS - DEFINE HIERARCHY, hierarchy_annot
ABAP CDS - DEFINE HIERARCHY, parameter_list