DDGetEntities()

Format

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

Returns

Returns the names of all parent or child entities in a hierarchy within a given depth. Optionally, the returned entities can be filtered by specifying a starting entity in the hierarchy and the templates which are expected to be assigned to them. 

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: The name of the hierarchy in which to search.
Behaviour: Required
Dimensions: SingleValue
Valid data types: String

Depth: The maximum number of levels to traverse in the hierarchy. Negative numbers indicate parent entities and positive numbers indicate child entities. E.g. 1 returns all immediate children, 2 returns all children and grandchildren, -1 returns all immediate parents, -2 returns all parents and grandparents.
Behaviour: Required
Dimensions: SingleValue
Valid data types: Integer

StartingEntity: The name of the entity at which to start the search. If this value is not specified, the function starts the search at the root of the hierarchy. See Common Traps below.
Behaviour: Optional (0..1)
Dimensions: SingleValue
Valid data types: String

Templates: List of template names that the returned entities must have assigned, within the time range of the fetch request. If an entity does not have one of these templates assigned, it will not appear in the results.
Behaviour: Optional (0..n)
Dimensions: SingleValue
Valid data types: String

How to properly format data types

Common Traps

Not specifying a StartingEntity means that the function should start at the root of the hierarchy.

If you are searching for entities but omitting the optional Templates parameter, you may also omit the StartingEntity parameter, or use an empty string. The following syntax examples are both acceptable:

DDGetEntities("myHierarchy",1)
or
DDGetEntities("myHierarchy",1,"")

If you want to get all of the first level entities with a specific template assigned, the syntax requires an empty string, as follows:

DDGetEntities("myHierarchy",1,"","myTemplate")

When to Use

The result of this function can be passed to DDGetAttributes() since it returns the entity names with the expected metadata.

Examples

Expression: DDGetEntities("myHierarchy", 2)
Result: Returns the name of all child and grandchild entities in "myHierarchy" starting from the root.

Expression: DDGetEntities("myHierarchy", 2, "myEntity")
Result: Returns the name of all child and grandchild entities in "myHierarchy" starting from "myEntity".

Expression: DDGetEntities("myHierarchy", 2, "", "myTemplate", "myTemplate2")
Result: Returns the name of all child and grandchild entities in "myHierarchy" starting from the root where the entity has "myTemplate" or "myTemplate2" assigned in the time range of the fetch request.

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

Expression: DDGetEntities("P2 Corporate", 2)
Result: P2 Energy Solutions, New South Wales, Queensland, South Australia, Victoria, Western Australia

Expression: DDGetEntities("P2 Corporate", 2,"Kimberley")
Result: Gibb, Meda, Sturt Creek, Billiluna, Tanami, Wolfe Creek, Kimbolton, May, Poultons, Bindarrie, Kalumburu, Nabberu

Expression: DDGetEntities("P2 Corporate", 3,"","Business Unit")
Result: New South Wales, Queensland, South Australia, Victoria, Western Australia

Expression: DDGetEntities("P2 Corporate", 3,"","Business Unit","Region")
Result: New South Wales, Queensland, South Australia, Victoria, Western Australia, GoldFields, Kimberley, Pilbara, Central Victoria, North East Victoria, North West Victoria, Barossa, Flinders Ranges, Murray River, Central West, Far North, North West, Far North Coast, Far West

Expression: DDGetEntities("P2 Corporate", -2,"Kimberley")
Result: Western Australia, P2 Energy Solutions