Registering a Comparative Metric¶

A comparative metric is a special type of virtual metric obtained by Common Data Service converting the time domain based on the comparative identifier in the metric expression.

Note

The capability to query comparative metrics does not rely on data sources, but is implemented by Common Data Service.
Time domain conversion works for the time range to query data rather than the timestamp of the returned data. The timestamp of the returned data remains the time stamped when request parameters are passed, so that the source metric and the comparative metric can be obtained and benchmarked in the same query at the same time.

The table below details the supported comparison types, comparison identifiers, and their corresponding time domain conversion methods.

Comparison Type	Comparison Identifier	Time Domain Conversion
Last Period	LP	If query period is Day(1)~Day(N), Common Data Service converts the period to Day(1-N)~Day(0). For example, if the query period is from April 1 to April 5, the corresponding Last Period is from March 27 to March 31.
Same Period Last Year	SPLY	If query period is Day(1)~Day(N), Common Data Service converts the period to Day(1)~Day(N) of last year. For example, if the query period is from April 1 to April 5, 2022, the corresponding Same Period Last Year is from April 1 to April 5, 2021.
Same Period Last Month	SPLM	If query period is Day(1)~Day(N), Common Data Service converts the period to Day(1)~Day(N) of last month. For example, if the query period is from April 1 to April 5, 2022, the corresponding Same Period Last Month is March 1 to March 5, 2022.

Comparative Metric Configuration Rules¶

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

In the Metric Key column, add a comparison identifier, for example, ActiveProductionSPLM. For more information, see Naming Rules of Unified Metric Keys.
In the Metric Name column, fill in a name based on the corresponding source metric using format SourceMetric(ComparisonIdentifier). For example, for source metric Production, its comparative metrics can be named Production(LP), Production(SPLY), and Production(SPLM).
In the Is Calculated column, fill in Y.
In the Expression column, include a comparison identifier in the expression using format #{Metric['SourceMetricAPIKey@@ComparisonIdentifier@@SourceMetricFieldKey']. For more information, see Comparative Metric Expression Examples.

Comparative Metric Expression Examples¶

The table below takes the Production metric in the solar domain (field Key is ActiveProduction and API Key is SolarAPI) as an example to illustrate its comparative metric expressions.

Comparison Type

Comparison Identifier

Expression

Last Period

LP

The expressions of the related LP metrics are as follows:

Production(LP): #{Metric[‘SolarAPI@@LP@@ActiveProduction’]}
Production(Period-over-Period): #{Metric[‘SolarAPI@@ActiveProduction’] / Metric[‘SolarAPI@@LP@@ActiveProduction’]}
Production(Period-over-Period Growth): #{Metric[‘SolarAPI@@ActiveProduction’] - Metric[‘SolarAPI@@LP@@ActiveProduction’]}
Production(Period-over-Period Growth Rate): #{(Metric[‘SolarAPI@@ActiveProduction’] - Metric[‘SolarAPI@@LP@@ActiveProduction’]) / Metric[‘SolarAPI@@LP@@ActiveProduction’]}

Same Period Last Year

SPLY

The expressions of the related SPLY metrics are as follows:

Production(SPLY): #{Metric[‘SolarAPI@@SPLY@@ActiveProduction’]}
Production(Year-over-Year): #{Metric[‘SolarAPI@@ActiveProduction’] / Metric[‘SolarAPI@@SPLY@@ActiveProduction’]}
Production(Year-over-Year Growth): #{Metric[‘SolarAPI@@ActiveProduction’] - Metric[‘SolarAPI@@SPLY@@ActiveProduction’]}
Production(Year-over-Year Growth Rate): #{(Metric[‘SolarAPI@@ActiveProduction’] - Metric[‘SolarAPI@@SPLY@@ActiveProduction’]) / Metric[‘SolarAPI@@SPLY@@ActiveProduction’]}

Same Period Last Month

SPLM

The expressions of the related SPLM metrics are as follows:

Production(SPLM): #{Metric[‘SolarAPI@@SPLM@@ActiveProduction’]}
Production(Month-over-Month): #{Metric[‘SolarAPI@@ActiveProduction’] / Metric[‘SolarAPI@@SPLM@@ActiveProduction’]}
Production(Month-over-Month Growth): #{Metric[‘SolarAPI@@ActiveProduction’] - Metric[‘SolarAPI@@SPLM@@ActiveProduction’]}
Production(Month-over-Month Growth Rate): #{(Metric[‘SolarAPI@@ActiveProduction’] - Metric[‘SolarAPI@@SPLM@@ActiveProduction’]) / Metric[‘SolarAPI@@SPLM@@ActiveProduction’]}