Registering a Cumulative Metric¶

A cumulative metric is the metric obtained by Common Data Service cumulating the values of the primary metric within a specific time period based on the time dimension identifier. When querying cumulative metrics through the Query Latest Metric API, you do not need to specify the time range.

The table below details the types, identifiers, and descriptions of the supported time dimensions and the supported query intervals of the corresponding primary metrics.

Time Dimension Type	Time Dimension Identifier	Description	Supported Query Interval of Primary Metric
Latest	L	The current time	L
Today	TD	From 0:00 of the current day to the current time	D
Month To Date	MTD	From 0:00 on the first day of the current month to the current time	M
Year To Date	YTD	From 0:00 on January 1 of the current year to the current time	Y
This Month	TM	From 0:00 on the first day of the current month to 0:00 on the first day of the next month	M
This Year	TY	From 0:00 on January 1 of the current year to 0:00 on January 1 of the next year	Y
Beginning Of Life	BOL	From the first data generation to the current time	T

Note

The difference between TM/TY and MTD/YTD is that TM/TY refers to a complete month/year while MTD/YTD refers to the month/year as of today.
The time dimensions only control the time range for Common Data Service to fetch data, and do not represent the time when data sources actually update the data. For example, if the last data update by the data source is at 5:00, when the TD data is queried at 5:04, the data up to 5:00 is returned.

Cumulative Metric Configuration Rules¶

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

In the Metric Key column, add a time dimension identifier as a suffix to the metric key, for example, PlannedYield:MTD. For more information, see Naming Rules of Unified Metric Keys.
In the Metric Name column, fill in a name based on the corresponding primary metric using format PrimaryMetric(TimeDimensionIdentifier). For example, for primary metric PlannedYield, its cumulative metrics can be named Yield(TD), Yield(TM), and Yield(BOL).
In the Is Calculated column, fill in the value consistent with the corresponding primary metric.
In the Primary Metric column, fill in the identifier of the corresponding primary metric, for example, PlannedYield.
In the Cumulative Metric Dimension column, fill in the time dimension identifier of the metric, for example, MTD. A cumulative metric has at most one time dimension identifier.