DDGetAttributes()

Format

DDGetAttributes(Entity Names, Attribute [,Entity Name Format])

Returns

Returns the values of the given attribute in a single collection for one or more entities, within the time range of the request.

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

EntityNames: A single value or a collection of values, where each value contains the entity name as metadata (see Useful to Know below). If a single string is passed as this parameter, then the function assumes that this string is the name of an entity and will not search for additional metadata, however all other single values throw an exception.  Note: Typically a DDGetEntities() call is used to provide the list of entities. Since DDGetAttributes() provides the necessary entity name metadata on the return values, these functions can also be nested. If the DD() function returns an error value, the error will be returned as is. If it returns Boolean values, the attribute will be fetched only if the value is true. In all other cases (date time, decimal, duration, integer, null, string) the attribute will be fetched. 
Behaviour: Required
Dimensions: Error, Collection, SingleValue, MultiCollection
Valid data types: Null, Boolean, DateTime, Decimal, Integer, String, Duration, Error

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

EntityNameFormat: A format string which can be used to alter the name of entities. #entity# defines the name of the entity, and any other characters in the string will be concatenated verbatim. E.g. "prefix #entity# suffix" will produce an entity name of "prefix entityname suffix".
Behaviour: Optional
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.

Examples

Expression: DDGetAttributes({ListOfTags}, 1, ":Attribute")
Result: Returns an error, as a simple list of tags does not have associated metadata.

Expression: DDGetAttributes("myEntity", "[myTemplate]:myAttribute!myAttributeValue")
Description: This function call behaves very similarly to a normal data object fetch like: {myEntity[myTemplate]:myAttribute!myAttributeValue}
Result: Returns the value of "myAttributeValue" on "myAttribute" on "myTemplate" of "myEntity"

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

Expression: DDGetAttributes(DDGetAttributes(DDGetEntities("myHierarchy", 2, "rootEntity"), ":myAttribute") > 15, ":myAttribute2")
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.

Expression: DDGetAttributes(DDGetEntities("myHierarchy", 1, "Field 1"), ":Oil Production", "P2 #entity#")
Result: Returns the values for {P2 Well 1:Oil Production},  {P2 Well 2:Oil Production}, and  {P2 Well 3:Oil Production}.

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

Expression: DDGetAttributes("Archer","[Oil Producing Well]:Choke")
Returns: The current choke position of well "Archer".
Result: 8.9660510928212

Expression: DDGetAttributes("Western Australia","[Business Unit]:Oil Production!Daily Production")
Returns: The daily oil production for Western Australia business unit.
Result: 82.6973713388189

Expression: DDGetAttributes(DDGetEntities("P2 Corporate", 3,"","Business Unit"),"[Business Unit]:Oil Production!Daily Production")
Returns: The daily oil production of all business units in the P2 Corporate hierarchy.
Result: 70.2447172581426 

Expression: DDGetAttributes(DDGetEntities("P2 Corporate", 5,"Western Australia","Oil Producing Well"),"[Oil Producing Well]:Status")
Returns: The status of all Oil Producing Wells in Western Australia, in the P2 Corporate hierarchy.
Result: 81.5040183167458  

Expression: DDGetAttributes(DDGetAttributes(DDGetEntities("P2 Corporate", 5, "Western Australia", "Oil Producing Well"), "[Oil Producing Well]:Status") == 0, ":Oil Production")
Returns: The total oil production of all Oil Producing Wells in Western Australia, in the P2 Corporate hierarchy, where the status of the well is 0.
Result: 16.3614824024781  

Release History

• DDGetAttributes() 4.6.5
  • Changed EntityNames parameter to support MultiCollection values.
• DDGetAttributes() 4.5.0
  • Initial version