Skip to content

Commit

Permalink
Instance annotations for recursive hierarchies (#258)
Browse files Browse the repository at this point in the history
  • Loading branch information
@HeikoTheissen
HeikoTheissen authored Sep 5, 2023
1 parent 47ad2a4 commit a199ef7
Show file tree
Hide file tree
Showing 3 changed files with 106 additions and 114 deletions.
69 changes: 34 additions & 35 deletions vocabularies/Hierarchy.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,66 +26,65 @@
"$AppliesTo": ["EntityType"],
"$BaseTerm": "Aggregation.RecursiveHierarchy",
"@Common.Experimental": true,
"@Core.Description": "Defines a recursive hierarchy",
"@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 annotation designates properties that contain derived information."
"@Common.IsInstanceAnnotation": true,
"@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 annotation contains derived information."
},
"RecursiveHierarchyType": {
"$Kind": "ComplexType",
"@Common.Experimental": true,
"@Core.LongDescription": "The property paths in this complex type refer to properties of an entity type that contain\ninformation about a node in a recursive hierarchy. When hierarchical transformations\nare applied whose first parameter has the annotated entity type\nand whose second parameter is the annotation qualifier,\nthen these properties are derived for each node in the result set.\nOtherwise, the property paths may evaluate to null.\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|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",
"ExternalKeyProperty": {
"$Type": "Edm.PropertyPath",
"@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|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": {
"$Nullable": true,
"@Core.Description": "String property holding the human-readable key value for a node",
"@Core.LongDescription": "If a `NodeTypeProperty` exists, the external key is unique only in combination with it.\n 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)."
"@Core.Description": "Human-readable key value for a node",
"@Core.LongDescription": "If a `NodeType` exists, the external key is unique only in combination with it.\n 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)."
},
"NodeTypeProperty": {
"$Type": "Edm.PropertyPath",
"NodeType": {
"$Nullable": true,
"@Core.Description": "String property holding the type of a node",
"@Core.Description": "Type of a node",
"@Core.LongDescription": "In a recursive hierarchy with mixed types, nodes can\n <br>- have a type-specific (navigation) property whose name is the node type or\n <br>- be represented by entities of different subtypes of a common entity type that is\n annotated with the `RecursiveHierarchy` annotation. The qualified name of the subtype is the node type."
},
"ChildCountProperty": {
"$Type": "Edm.PropertyPath",
"ChildCount": {
"$Type": "Edm.Int64",
"$Nullable": true,
"@Core.Description": "Integer property of type `Edm.Int64` holding the number of children a node has in the unlimited hierarchy"
"@Core.Description": "Number of children a node has in the unlimited hierarchy"
},
"DescendantCountProperty": {
"$Type": "Edm.PropertyPath",
"DescendantCount": {
"$Type": "Edm.Int64",
"$Nullable": true,
"@Core.Description": "Integer property of type `Edm.Int64` holding the number of descendants a node has in the unlimited hierarchy"
"@Core.Description": "Number of descendants a node has in the unlimited hierarchy"
},
"LimitedDescendantCountProperty": {
"$Type": "Edm.PropertyPath",
"LimitedDescendantCount": {
"$Type": "Edm.Int64",
"$Nullable": true,
"@Core.Description": "Integer property of type `Edm.Int64` holding the number of descendants a node has in the limited hierarchy"
"@Core.Description": "Number of descendants a node has in the limited hierarchy"
},
"DrillStateProperty": {
"$Type": "Edm.PropertyPath",
"@Core.Description": "String property holding the drill state of a node",
"DrillState": {
"$Nullable": true,
"@Core.Description": "Drill state of an occurrence of a node",
"@Core.LongDescription": "Possible drill states are:\n <br>- `expanded` if a node has children in the limited hierarchy\n <br>- `collapsed` if a node has children in the unlimited hierarchy but not in the limited hierarchy\n <br>- `leaf` if a node has no children in the unlimited hierarchy"
},
"DistanceFromRootProperty": {
"$Type": "Edm.PropertyPath",
"DistanceFromRoot": {
"$Type": "Edm.Int64",
"$Nullable": true,
"@Core.Description": "Integer property of type `Edm.Int64` holding the number of ancestors a node has in the limited hierarchy",
"@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 as well as in the unlimited hierarchy."
},
"SiblingRankProperty": {
"$Type": "Edm.PropertyPath",
"SiblingRank": {
"$Type": "Edm.Int64",
"$Nullable": true,
"@Core.Description": "Integer property of type `Edm.Int64` holding the sibling rank of a node",
"@Core.Description": "Sibling rank of a node",
"@Core.LongDescription": "The sibling rank of a node is the index of the node in the sequence of all nodes\n in the unlimited hierarchy with the same parent. The first sibling has rank 0."
},
"MatchedProperty": {
"$Type": "Edm.PropertyPath",
"Matched": {
"$Type": "Edm.Boolean",
"$Nullable": true,
"@Core.Description": "Boolean property indicating [matching](#MatchCount) nodes"
"@Core.Description": "Flag indicating [matching](#MatchCount) nodes"
},
"MatchedDescendantCountProperty": {
"$Type": "Edm.PropertyPath",
"MatchedDescendantCount": {
"$Type": "Edm.Int64",
"$Nullable": true,
"@Core.Description": "Integer property of type `Edm.Int64` holding the the number of [matching](#MatchCount) descendants a node has in the unlimited hierarchy"
"@Core.Description": "Number of [matching](#MatchCount) descendants a node has in the unlimited hierarchy"
}
},
"RecursiveHierarchyActions": {
Expand Down Expand Up @@ -118,7 +117,7 @@
"@Common.Experimental": true,
"@Common.IsInstanceAnnotation": true,
"@Core.Description": "Instance annotation on the result of an `$apply` query option containing the number of matching nodes after hierarchical transformations",
"@Core.LongDescription": "The service designates a subset of the `$apply` result as \"matching nodes\".\n This subset is the output set of the `filter` or `search` transformation that occurs as the fourth parameter\n of the last `ancestors` transformation or occurs nested into it.<br>\n This instance annotation is available if [`RecursiveHierarchy/MatchedProperty`](#RecursiveHierarchyType)\n and `RecursiveHierarchy/MatchedDescendantCountProperty` are also available."
"@Core.LongDescription": "The service designates a subset of the `$apply` result as \"matching nodes\".\n This subset is the output set of the `filter` or `search` transformation that occurs as the fourth parameter\n of the last `ancestors` transformation or occurs nested into it."
},
"TopLevels": [
{
Expand Down
Loading

0 comments on commit a199ef7

Please sign in to comment.