Key Concepts¶

The user and permission system of Common Data Service is inherited from EnOS Application Portal. Before you start, you need to learn about the key concepts of EnOS Application Portal.

Below are the key concepts of Common Data Service.

Data Source¶

Data sources are the basis for querying data using Common Data Service. Data providers need to standardize the data source APIs according to specifications and register the APIs in Common Data Service, so that data consumers can query the relevant data using Common Data Service.

Data sources can be divided into the following types according to their effective scope.

Public data sources take effect for all OUs.
Private data sources take effect for the current OU only.

For more information, see Registering a Data Source.

Virtual Attribute¶

An attribute describes the static information of an asset and is defined on the EnOS model. For example, the name and model of an inverter, and the latitude and longitude of a solar site. For more information, see Device Modeling.

A virtual attribute is not the attribute defined on the EnOS model, but a non-model attribute defined by an expression calculated based on one or more parameters. The parameters can be attributes from the EnOS model, attributes provided by the registered data source APIs, and constants. For example, Common Data Service can define a virtual attribute Number of Running Inverters which is calculated by number of normally running inverters + number of running inverters in low performance + number of running inverters with limited power. For more information, see Registering a Virtual Attribute.

Virtual attributes can be divided into the following types according to their effective scope.

Public attributes take effect for all OUs in the current environment.
Private attributes take effect for the current OU only.

Common Data Service can be used to query both EnOS model attributes and virtual attributes.

Virtual Measurement Point¶

A measurement point describes the runtime state of an asset and is defined on the EnOS model. For example, temperature, pressure, current, and voltage. For more information, see Device Modeling.

A virtual measurement point is not the point defined on the EnOS model, but a non-model point defined by an expression calculated based on one or more parameters. The parameters can be model points, constants, and attributes. For example, Common Data Service can define a virtual point Power Ratio which is calculated by ActivePower/Capacity. For more information, see Registering a Virtual Measurement Point.

Virtual measurement points can be divided into the following types according to their effective scope.

Public measurement points take effect for all OUs in the current environment.
Private measurement points take effect for the current OU only.

Common Data Service can be used to query both EnOS model points and virtual points.

Metric¶

Metrics are statistical values that measure the overall characteristics of a target, and are numerical indicators to reflect the business status of a certain business activity. For example, production, production loss, and failure rate.

Metrics in Common Data Service can be divided into public and private metrics according to the effective scope and source and unified metrics according to the usage.

Public/Private Metric¶

Metrics can be divided into the following types according to their effective scope.

Public metrics take effect for all OUs in the current environment.
Private metrics take effect for the current OU only.

If the metric keys of a private metric and a public metric are duplicated, Common Data Service returns the private metric when the metric key is used for data query.

Unified/Source Metric¶

Metrics can be divided into the following types according to their usage.

Source metrics: the metrics provided by the data source APIs. Source metrics can only be used for defining unified metrics, and cannot be queried through Common Data Service APIs. For more information, see Registering a Source Metric.
Unified metrics: the metrics exposed externally by Common Data Service APIs. Unified metrics are the query objects of Common Data Service APIs directly facing data consumers. For more information, see Registering a Unified Metric.

Primary/Cumulative Metric¶

Common Data Service can quickly query some metrics for a fixed time period, such as the current day, the current month, and the current year. For example, based on the Yield metric, Common Data Service can register the Yield:TD metric, which returns the yield hours between 0:00 and the current time point.

Unified metrics can be divided into the following types according to whether they support fixed query period:

Primary metrics: general metrics which require users to specify the time range when querying data in a certain period.
Cumulative metrics: sub-metrics of general metrics whose metric keys include time dimension identifiers such as TD (current day), MTD (current month), and YTD (current year). Users do not need to specify the time range when querying cumulative metrics. For more information, see Registering a Cumulative Metric.

In the Unified Metrics menu, all cumulative metrics are automatically mounted under the associated primary metrics. Click the plus icon in front of a primary metric to view all cumulative metrics associated with it.

Passthrough/Virtual Metric¶

In simple scenarios, there is a one-to-one correspondence between source metrics and unified metrics. But in complex scenarios, unified metrics are the extension of source metrics.

Unified metrics are divided into the following types according to their relationship with source metrics:

Passthrough metrics: the unified metrics that correspond one-to-one with source metrics.
Virtual metrics: also known as calculated metrics, the unified metrics calculated based on source metrics and expressions. There is not a one-to-one correspondence between virtual metrics and source metrics. The expressions of virtual metrics can contain such logic as four basic arithmetic operations and conditional statements, and the expression results are not directly provided by data sources, but returned by Common Data Service calculating the expressions in real time for each query. Such metrics are not stored in Common Data Service and therefore called “virtual metrics”. For more information, see Registering a Virtual Metric.

Comparative Metric¶

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

A period-over-period metric refers to the last statistical period connected with the original statistical period. For example, for the Production(Last Period) metric, if the query period is April 1 ~ April 5, Common Data Service returns the production from March 27 to March 31.
A year-over-year metric refers to the same period last year, and a month-over-year metric refers to the same period last month. For example, for the Production(Same Period Last Year) metric and the Production(Same Period Last Month) metric, if the query period is April 1 to April 5, 2022, Common Data Service respectively returns the production from April 1 to April 5, 2021 and the production from March 1 to March 5, 2022.

For more information, see Registering a Comparative Metric.

Record Type¶

A record type is the type of non-time-series fact data such as alarm, warning, service request, and work order. Different from time-series data such as metrics and measurement points, record types have no query interval, and do not support aggregation calculation and virtual data configuration.

Record types can be divided into the following types according to their effective scope.

Public record types take effect for all OUs in the current environment.
Private record types take effect for the current OU only.

For more information, see Registering a Record Type.

Dimension Type¶

A dimension type can be referenced by a unified metric to define its supported aggregation dimension such as asset type, province, and manufacturer.

Dimension types can be divided into the following types according to their effective scope.

Public dimension types take effect for all OUs in the current environment.
Private dimension types take effect for the current OU only.

For more information, see Registering a Dimension Type.

Object Type¶

An object type (mdm type) can be referenced by a metric, a measurement point, or an attribute to define the asset type it belongs to. Object types include multiple levels, for example, site types (such as wind farm and building), device types (such as meter and energy storage system), and component types (such as battery bank and battery rack).

Object types can be divided into the following types according to their effective scope.

Public object types take effect for all OUs in the current environment.
Private object types take effect for the current OU only.

For more information, see Registering an Object Type.