Derived metrics can be used to compute new values by using an expression based on the value of other metrics.
The expression result could be a number, a boolean or a string value.

Creating a Derived metric

To add a new Derived metric to a Thing Definition, you should:

Enter the Computed Data page.
Select the Thing Definitions tab.
Select the Thing Definition to edit.
Press the Add Metric button.
Select the Derived type and provide the required information.
Press the Save button and edit the additional information, if needed.

Editing a Derived metric

The configuration of a Derived metric is subdivided into several sections:

General

Label: the metric label shown within the widget.
Name: the name of the metric, also used to reference it within the dashboard's templates.
Description: the text describing the metric.
The description is displayed as a tooltip within the dashboard widgets.
Unit: the unit of measurement (e.g. Kg, °C, pieces, liters...etc.)
Group: the group the metric belongs to (e.g. Temperatures, System).
Privatizable by customer: allow the customer to define whether the metric is private or not.
For more details, refer to this Privatizable date article.

Computation

You can configure whether the computation is to be Continuous or Sampled.
The Continuous computation takes into account all input values and can generate the same number of output values, while the Sampled computation is just based on the last available value and generates only one output value per sampling period (e.g. 1h, 1d).

Both Sampled and Continuous computations are periodically evaluated at a fixed time interval.

By using the Sample computation, you can reduce the number of consumed DPH, and, in addition, you can reference more input variables than Continuous.
For old metrics with sampling period defined, a warning inform you to choose to clear the sampling period or change the computation to Sampled.

Suppose you have a derived metric that sums two other metrics, here we resume the different behaviors in the case of Continuous and Sampled (1 hour) computation.

Output = Metric1 + Metric2

The Timestamp column represent the time when the value comes available.

			OUTPUT
Timestamp	Metric1	Metric2	Continuous	Sampled (1h)
10:00	10	20	30	30
10:10	20	20	40	-
10:20	20	10	30	-
10:40	20	30	50	-
11:00	-	50 (10:40)
11:10	15	20	35	-

Note that the Sampled computation is performed every sampling period with a few seconds delay; using the last received values the new value is computed, and stored using the last received timestamp. So, for example, at 11:00, the computation is performed, but the resulting value "50" is stored using the 10:40 timestamp corresponding to the last value of Metric2.

In either case, the computed values might come available with a few seconds delay from the input values. This delay could depend on the complexity of the derivation to be processed for each thing:

Number of computed metrics.
Number of DPH input to each computed metric (in case of Continuous evaluation).
Computed metrics uses as input into other computed metrics, and so on.

Computation on input updated
Computed metrics are only calculated if at least one of the input metrics has newer data than the last computation.

Derivation

In the derivation panel, it is possible to select one or more metrics or properties to use within the expression. In addition, you can refer to the previous value calculated for the metric. Note that, the number of selectable metrics depends on the computation policy. In case of Continuous computation, you can select up to 3 metrics.

Once the metrics/properties have been selected, it is possible to configure the derivation expression, here are some examples:

// total weight in kg
(unitWeight * quantity)/1000

// milliseconds to hour
#floor(time / 3600000)

// substring
alertCode.#substring(3,6)

// energy increment in kWh
(energy / 1000) - previousValue

Values encoding into expressions:

Type	Sample Encoding
STRING	`'foobar'`
BOOLEAN	`true` or `false`
INTEGER	`123`
FLOAT	`123.456`

By pressing the Add Condition button, it is possible to add multiple result conditions to implement the IF, ELSE, OTHERWISE pattern.

Previous Input Metric Value

When referring to a metric, you can access not only its current value but also its previous value. In this way you can use the difference of consecutive values into your derivation logic.

outputPieces - outputPieces.PREVIOUS

Null Result

In case the result expression, of the activated case (including the default one) is empty, no new data is stored in the database.

For instance:

IF metric1 > 100 → left the result empty to do nothing
ELSE RETURN (metric1 + metric2) → save new value

Functions

The expression language used to define Derived Metric expressions is based on the following operators.

OPERATOR	NOTATION	SAMPLE
Mathematical	+ - * / % ^	(x + y^2)/4
Logical	or and true/false	x==y && (b==true \|\| b==c)
Relational	==, !=, <, <=, >=, >	a != b
Elvis	Ternary operator	condition ? foo : bar

It is possible to use this predefined set of functions.

MATH	DESCRIPTION	SAMPLE
cos	Returns the trigonometric cosine of an angle, in radians.	#cos(x)
sen	Returns the trigonometric sine of an angle, in radians.	#sen(x)
abs	Returns the absolute value of a numeric value.	#abs(x)
sqrt	Returns the rounded positive square root of a numeric value.	#sqrt(x)
pi	The PI value (3.14159…).	#pi
ceil	Returns the smallest integer value greater than or equal to the float argument.	#ceil(x)
floor	Returns the largest integer value that is less than or equal to the float argument.	#floor(x)
log	Returns the natural logarithm (base e) of the argument.	#log(x)
log10	Returns the base 10 logarithm of the argument.	#log(x)
max	Returns the greater of two values.	#max(x, y)
min	Returns the smallest of two values.	#min(x, y)
pow	Returns the value of the first argument raised to the power of the second argument.	#pow(x, exp)
CONVERSION	DESCRIPTION	SAMPLE
parseInt	Converts the string argument to integer using the given radix (optional).	#parseInt('12') #parseInt('BF123', 16)
intToString	Converts an integer to string using a radix.	#intToString(123456, 16)
parseFloat	Converts the string argument to float using the given radix (optional).	#parseFloat('12.3')
floatToString	Converts a float to string using a radix.	#floatToString(12.3)
toString	Converts the source value to string.	var.#toString()
STRING	DESCRIPTION	SAMPLE
substring	Returns a substring considering the start (inclusive) and end (exclusive) zero based indexes.	str.#substring(startIndex) str.#substring(startIndex, endIndex)
length	Returns the length of the string.	str.#length()
charAt	Returns the character at the specified index.	str.#charAt(index)
indexOf	Returns the index (zero-based) of the first occurrence of the argument string.	str.#indexOf('foo')
lastIndexOf	Returns the index (zero-based) of the last occurrence of the argument string.	str.#lastIndexOf('foo')
split	Returns the arrays of tokens splitting by the argument string.	str.#split(',')
toUpperCase	Converts the source string to upper-case.	str.#toUpperCase()
toLowerCase	Converts the source string to lower case.	str.#toLowerCase()

Data

In case of numeric metrics, the Data Type allows you to define whether the metric values are DISCRETE or CONTINUOUS, and then you can also define Dictionary and Thresholds.

Derived Metrics