{"id":28003,"date":"2017-06-16T14:16:49","date_gmt":"2017-06-16T06:16:49","guid":{"rendered":"http:\/\/localhost\/help\/?page_id=28003"},"modified":"2024-01-17T10:47:59","modified_gmt":"2024-01-17T02:47:59","slug":"ddgetattributes","status":"publish","type":"page","link":"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/calculations\/ddgetattributes\/","title":{"rendered":"DDGetAttributes()"},"content":{"rendered":"\n

Format<\/h2>\n

DDGetAttributes(Entity Names, Attribute [,Entity Name Format])<\/strong><\/p>\n

Returns<\/h2>\n

Returns the values of the given attribute in a single collection for one or more entities, within the time range of the request.<\/p>\n

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.<\/p>\n

Inputs<\/h2>\n

EntityNames: <\/b>A single value or a collection of values, where each value contains the entity name as metadata (see Useful to Know<\/a> 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. \u00a0Note: 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.\u00a0If 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.\u00a0
\nBehaviour: Required
\nDimensions: Error, Collection, SingleValue, MultiCollection
\nValid data types: Null, Boolean, DateTime, Decimal, Integer, String, Duration, Error<\/p>\n

Attribute: <\/b>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<\/span>). The entity name is provided by the first parameter. If the [TemplateName<\/em>] is omitted, the function will assume the attribute belongs to the entity's primary template.\u00a0
\nBehaviour: Required
\nDimensions: SingleValue
\nValid data types: String<\/p>\n

EntityNameFormat: <\/b>A format string which can be used to alter the name of entities. #entity#<\/strong><\/em> defines the name of the entity, and any other characters in the string will be concatenated verbatim. E.g. \"prefix #entity# suffix<\/em>\" will produce an entity name of \"prefix entityname suffix<\/em>\".
\nBehaviour: Optional
\nDimensions: SingleValue
\nValid data types: String<\/p>\n

How to format data types<\/a><\/p>\n

Useful to Know<\/h2>\n

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.<\/p>\n

Examples<\/h2>\n

Expression: DDGetAttributes({ListOfTags}, 1, \":Attribute\")<\/span>
\nResult: Returns an error, as a simple list of tags does not have associated metadata.<\/p>\n

Expression: DDGetAttributes(\"myEntity\", \"[myTemplate]:myAttribute!myAttributeValue\")<\/span>
\nDescription: This function call behaves very similarly to a normal data object fetch like: {myEntity[myTemplate]:myAttribute!myAttributeValue}
\nResult: Returns the value of \"myAttributeValue\" on \"myAttribute\" on \"myTemplate\" of \"myEntity\"<\/p>\n

Expression: DDGetAttributes(DDGetEntities(\"myHierarchy\", 2, \"rootEntity\"), \":myAttribute\")<\/span>
\nResult: Returns the value of \"myAttribute\" for each child entity maximum 2 levels below the \"rootEntity\" in \"myHierarchy\".<\/p>\n

Expression: DDGetAttributes(DDGetAttributes(DDGetEntities(\"myHierarchy\", 2, \"rootEntity\"), \":myAttribute\") > 15, \":myAttribute2\")<\/span>
\nResult: 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.<\/p>\n

Expression: DDGetAttributes(DDGetEntities(\"myHierarchy\", 1, \"Field 1\"), \":Oil Production\", \"P2 #entity#\")<\/span>
\nResult: Returns the values for {P2 Well 1:Oil Production}, \u00a0{P2 Well 2:Oil Production}, and \u00a0{P2 Well 3:Oil Production}.<\/p>\n

Tip: If you have access to the sample data, try running the following examples using the calculation tester<\/a>.\u00a0<\/p>\n

Expression: DDGetAttributes(\"Archer\",\"[Oil Producing Well]:Choke\")
\n<\/span>Returns: The current choke position of well \"Archer\".
\nResult: 8.9660510928212<\/span><\/p>\n

Expression: DDGetAttributes(\"Western Australia\",\"[Business Unit]:Oil Production!Daily Production\")
\n<\/span>Returns: The daily oil production for Western Australia business unit.
\nResult: 82.6973713388189<\/span><\/p>\n

Expression: DDGetAttributes(DDGetEntities(\"P2 Corporate\", 3,\"\",\"Business Unit\"),\"[Business Unit]:Oil Production!Daily Production\")
\n<\/span>Returns: The daily oil production of all business units in the P2 Corporate hierarchy.
\nResult: 70.2447172581426<\/span>\u00a0<\/p>\n

Expression: DDGetAttributes(DDGetEntities(\"P2 Corporate\", 5,\"Western Australia\",\"Oil Producing Well\"),\"[Oil Producing Well]:Status\")
\n<\/span>Returns: The status of all Oil Producing Wells in Western Australia, in the P2 Corporate hierarchy.
\nResult: 81.5040183167458<\/span>\u00a0\u00a0<\/p>\n

Expression: DDGetAttributes(DDGetAttributes(DDGetEntities(\"P2 Corporate\", 5, \"Western Australia\", \"Oil Producing Well\"), \"[Oil Producing Well]:Status\") == 0, \":Oil Production\")
\n<\/span>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.
\nResult: 16.3614824024781<\/span> \u00a0<\/p>\n

Release History<\/span><\/h2>\n