Registering a Virtual Metric


A virtual metric is a unified 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.