DDGet()

Format

DDGet(Hierarchy ,Depth ,Starting Entity ,Attribute [,Condition] [,Templates])

Returns

Returns the value of the specified attribute of each matching child/parent entity in the specified hierarchy, in a single collection.

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

Starting Entity: The name of the entity at which to start the search. 
Behaviour: Required
Dimensions: SingleValue
Valid data types: String

Attribute: The attribute or attribute value to fetch for each entity. The format must follow the syntax used for fetching data objects (i.e. [TemplateName]:Attribute!AttributeValue). The entity name is provided by the first parameter. If the [TemplateName] is omitted, the function will assume the attribute belongs to the entity's primary template. 
Behaviour: Required
Dimensions: SingleValue
Valid data types: String

Condition: A condition which filters the list of entities to fetch data for. Attribute names can be specified in the condition using the data object fetch syntax, but without entity names as entities will be provided by metadata e.g. {[myTemplate]:myAttribute!myAttributeValue} > 15. If the condition is omitted, the function returns the values for all entities.
Behaviour: Optional
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. If the template filter is omitted, the fetch will be attempted on all entities (regardless of template) and errors will be returned if the entities don’t have the attribute specified in the 4th parameter.
Behaviour: Optional (0..n)
Dimensions: SingleValue
Valid data types: String

How to format data types

Useful to Know

In the calculation engine, values returned by DD() functions have metadata assigned to them, such as entity name and start/end times. Other DD() functions can use this metadata to assign additional information to values they receive. In this way, the metadata is used by nested DD() functions to reduce complexity but increase versatility. Which metadata is used and how it is used is specific to each function, and is described in the Input Values section above, where applicable.

When to Use

This function can be used in place of a nested DDGetAttributes(DDGetAttributes(DDGetEntities)) function.

• Use DDGetAttributes() to fetch the values of an entity attribute.
  Use DDGet() to fetch the values of an entity attribute, when a condition is met and/or you want to filter by a particular template.
   
• Use DDGet() to fetch the values of an entity attribute.
  Use DDGetEntities() to get the names of the entities.

Examples

Expression: DDGet("myHierarchy", 2, "rootEntity", ":myAttribute")
Result: Returns the value of "myAttribute" for each child entity maximum 2 levels below the "rootEntity" in "myHierarchy".

Expression: DDGet("myHierarchy", 2, "rootEntity", ":myAttribute2", "{:myAttribute} > 15")
Result: Returns the value of "myAttribute2" for each child entity maximum 2 levels below the "rootEntity" in "myHierarchy" where the value of "myAttribute" is greater than 15.

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

Expression: DDGet("P2 Corporate", 5, "Western Australia", ":Oil Production", "{[Oil Producing Well]:Status} == 0", "Oil Producing Well")
Returns: The total oil production of each Oil Producing Well in Western Australia, in the P2 Corporate hierarchy, where the well is online (status is 0). This is effectively the same as the function DDGetAttributes(DDGetAttributes(DDGetEntities("P2 Corporate", 5, "Western Australia", "Oil Producing Well"), "[Oil Producing Well]:Status") == 0, ":Oil Production").
Result: 24.8919960227292