Registering a Virtual Metric


A virtual metric is a business metric calculated based on the source metric in the expression. Virtual metrics do not have a one-to-one correspondence with source metrics.

Note

  • Common Data Service calculates and returns virtual metrics in real time during data query, but does not store the data in the database. Therefore, virtual metrics can only be used in lightweight calculation scenarios such as four basic arithmetic operations and some special syntax. For more information about the supported syntax, see the Virtual Metric Expression Examples section.
  • For complex calculation scenarios where expressions require multiple layers of nesting, it is recommended to perform pre-calculation in the data source before registering metrics in Common Data Service to ensure data query performance.

Virtual Metric Configuration Rules


To register a virtual metric, you need to follow the configuration rules below when filling up the template file.


  • In the Is Calculated column, fill in Y.

  • In the Expression column, fill in an expression based on one or more source metrics together with attributes or constants by referring to Spring Expression Language.

    • Use this format to reference a source metric: #{Metric['SourceMetricAPIKey@@ComparisonIdentifier@@SourceMetricFieldKey']. Note that ComparisonIdentifier@@ can be included in the expression only when you register a comparative metric.
    • Use this format to reference an attribute: Attribute['AttributeIdentifier'].

    Note

    To ensure performance, it is recommended that you reference no more than 3 source metrics in an expression.

    For more information, see Virtual Metric Expression Examples.

Virtual Metric Expression Examples


The table below lists the typical examples of virtual metric expressions.


Scenario Expression Syntax Metric Example Expression Example Expression Description
Division of metrics by metrics Expression syntax: A/B. Both A and B are metrics. Production Plan Completion Rate #{Metric[‘GSSCAPI@@production’] * 100 / Metric[‘GSSCAPI@@production_plan’]} Divide Production by PlannedProduction and convert the result into a percentage
Division of metrics by attributes Expression syntax: A/B. A is a metric and B is an attribute. Yield #{Metric[‘WindAPI@@WENL_GENERAL_REPORT_SUM.PRODUCTION_ACTIVE’] / 1000 / Attribute[‘capacity’]} Divide Production by Capacity
Conditional statement Expression syntax: A?B:C. A is a condition. Output B if A is true and output C if false. This syntax is usually used to evaluate whether the elements of the expression and the relationship between them conform to the business logic, and output a default value or null if not. Performance Ratio #{Metric[‘SolarAPI@@INV.PR’] >0 ? Metric[‘SolarAPI@@INV.PR’] * 100 : null} If Performance Ratio is greater than 0, return it as a percentage, otherwise return null
Null conversion Expression syntax: A?B. A is a basic expression. Output B if A is null, and output A if not. This syntax is often used to avoid the situation where a single addend is null and the system outputs null as result when multiple metrics are added. Expected Production #{(Metric[‘SolarAPI@@SITE.RecoverableProduction’]?:0) + (Metric[‘SolarAPI@@SITE.ActualProdLoss’]?:0)} Add Recoverable Production and Actual Production Loss. If any addend is null, convert it to 0
Forced aggregation Expression syntax: SUM#(A#). A is a basic expression. This syntax takes precedence over the inherent aggregation methods of metrics. When Common Data Service performs multi-object aggregation on A, it forces the use of summation, ignoring the original aggregation method of A. If multiple metrics are included in expression A, Common Data Service first calculates A of a single object, and then aggregate metrics of multiple objects through summation. Irradiance (Capacity-weighted Average) #{SUM#(Metric[‘SolarAPI@@SITE.Radiation2ACC’]*Metric[‘SolarAPI@@SITE.ConvertedCapacity’]#)/SUM#(Metric[‘SolarAPI@@SITE.ConvertedCapacity’]#)} Divide SUM(Irradiance×Capacity) by SUM(Capacity). Only if Irradiance and Capacity of a single object are both null, the object is not included in the aggregation
Aggregation filtering Expression syntax: /*anynull*/A. A is a basic expression. If one or more metrics of a single object are null, the object is not included in the multi-object aggregation. If this syntax is not used, the default logic is only when all the metrics of a single object are null, the object is not included in the multi-object aggregation. Irradiance (Capacity-weighted Average) #{/*anynull*/SUM#(Metric[‘SolarAPI@@SITE.Radiation2ACC’]*Metric[‘SolarAPI@@SITE.ConvertedCapacity’]#)/SUM#(Metric[‘SolarAPI@@SITE.ConvertedCapacity’]#)} Divide SUM(Irradiance×Capacity) by SUM(Capacity). When Irradiance and Capacity of a single object are all null, or when either of them is null, the object is not included in the aggregation
JSON parsing Expression syntax: #jsonPath(A,’KEY’). A is a metric, measurement point, or attribute. Get the value whose key is KEY from A. Inverter State #{#jsonPath(Point[‘INV.StateAttr’],’DELIVERY’)!=0 ? 1 : 0} Parse the INV.StateAttr measurement point (content format is JSON), get the value corresponding to the DELIVERY key, and evaluate whether the value is 0. If it is, output 0, otherwise output 1.