DDGetParent()

Format

DDGetParent(Hierarchy, StartingEntity, Depth [,Templates])

Returns

Returns the name of the first matching parent entity in the specified hierarchy.

The function could be read as, "In the Hierarchy hierarchy, starting at StartingEntity, search up to Depth levels above for the first entity that has one or more of the Templates assigned".

It is possible to retrieve very large volumes of data through indiscriminate use of this function. Retrieving large amounts of Historian data across a slow network can affect system performance for all users of the system.

Inputs

Hierarchy: Name of the hierarchy in which to search. 
Behaviour: Required
Dimensions: SingleValue
Valid data types: String

StartingEntity: Name of the entity at which to start the search. 
Behaviour: Required
Dimensions: SingleValue
Valid data types: String

Depth: The maximum number of levels in the hierarchy to iterate over. The first matching entity will be returned (i.e. if a match is found at level 1, this is returned even if there is another matching entity at level 2). Must be a negative number e.g. -1 searches all immediate parents, -2 searches all parents and grandparents. Note that if the Templates parameter is omitted, the Depth parameter is essentially ignored and the immediate parent entity will always be returned. 
Behaviour: Required
Dimensions: SingleValue
Valid data types: Integer

Templates: List of template names that the matching parent entity must have assigned within the time range of the fetch request.
Behaviour: Optional (0..1)
Dimensions: SingleValue
Valid data types: String

How to properly format data types

Common Traps

When an entity exists in multiple places in the hierarchy and thus has multiple parent entities, the function returns the first applicable parent it encounters in the database during processing. See the examples below to understand the results.

Examples

The following examples show the expected results when the StartingEntity only appears once in the hierarchy:

Expression: DDGetParent("myHierarchy", "myEntity", -1)
Result: Returns the name of the first parent entity of "myEntity" in "myHierarchy".

Expression: DDGetParent("myHierarchy", "myEntity", -2, "myTemplate")
Result: Returns the name of the first parent or grandparent entity which has "myTemplate" assigned in the time range of the fetch request from "myHierarchy" starting from "myEntity".

Tip: If you have access to the sample data, try running the following examples using the calculation tester. 

Expression: DDGetParent("P2 Corporate","Archer",-3)
Returns the name of the first parent at 1, 2, or 3 levels above the entity "Archer" in the "P2 Corporate" hierarchy, regardless of template assigned, during the fetch request period.
Result: Coen

Expression: DDGetParent("P2 Corporate","Earl",-3,"Business Unit")
Returns the name of the first entity at 1, 2, or 3 levels above the entity "Earl" in the "P2 Corporate" hierarchy, that has the "Business Unit" template assigned during the fetch request period.
Result: New South Wales

Expression: DDGetParent("P2 Corporate","Earl",-3,"Area","Production")
Returns the name of the first entity at 1, 2, or 3 levels above the entity "Earl" in the "P2 Corporate" hierarchy, that has the "Area" or "Production" template assigned during the fetch request period.
Result: Graphton

 

The following examples show the expected results when the StartingEntity appears more than once in the hierarchy:

For example, given this hierarchy:

Country [CountryTemplate]
|--- Region 1 [RegionTemplate]
    |--- Field 1 [FieldTemplate]
        |--- Well 1 [WellTemplate]
    |--- Field 2 [ Field]
        |--- Well 1 [WellTemplate]

The following examples show the expected results:

Expression: DDGetParent("Hierarchy", "Well 1", -3)
Result: Field 1 or Field 2

Expression: DDGetParent("Hierarchy", "Well 1", -3, "Field")
Result: Field 1 or Field 2

Expression: DDGetParent("Hierarchy", "Well 1", -3, "Region")
Result: Region 1

Expression: DDGetParent("Hierarchy", "Well 1", -3, "Country")
Result: Country

Expression: DDGetParent("Hierarchy", "Well 1", -3, "Country", "Region")
Result: Region 1

Expression: DDGetParent("Hierarchy", "Well 1", -3, "Country", "Region", "Field")
Result: Field 1 or Field 2