22. Expression Datum Filter¶

The Expression Datum Filter provides a way to generate new properties by evaluating expressions against existing properties.

This filter is provided by the Standard Datum Filters plugin.

22.1 Settings¶

Each filter configuration contains the following overall settings:

Setting	Description
Service Name	A unique ID for the filter, to be referenced by other components.
Service Group	An optional service group name to assign.
Source ID	A case-insensitive pattern to match the input source ID(s) to filter. If omitted then datum for all source ID values will be filtered, otherwise only datum with matching source ID values will be filtered.
Required Mode	If configured, an operational mode that must be active for this filter to be applied.
Required Tag	Only apply the filter on datum with the given tag. A tag may be prefixed with `!` to invert the logic so that the filter only applies to datum without the given tag. Multiple tags can be defined using a `,` delimiter, in which case at least one of the configured tags must match to apply the filter.
Expressions	A list of expression configurations that are evaluated to derive datum property values from other property values.

Use the + and - buttons to add/remove expression configurations.

22.2 Expression settings¶

Each expression configuration contains the following settings:

Setting	Description
Property	The datum property to store the expression result in.
Property Type	The datum property type to use.
Expression	The expression to evaluate. See below for more info.
Expression Language	The expression language to write Expression in.

22.3 Expressions¶

See the SolarNode Expressions guide for general expressions reference. The root object is a DatumExpressionRoot that lets you treat all datum properties, and filter parameters, as expression variables directly, along with the following properties:

Property	Type	Description
`datum`	`Datum`	A `Datum` object, populated with data from all property and virtual meter configurations.
`props`	`Map<String,Object>`	Simple Map based access to the properties in `datum`, and transform parameters, to simplify expressions.

The following methods are available:

Function	Arguments	Result	Description
`has(name)`	`String`	`boolean`	Returns `true` if a property named `name` is defined.
`hasLatest(source)`	`String`	`boolean`	Returns `true` if a datum with source ID `source` is available via the `latest(source)` function.
`latest(source)`	`String`	`DatumExpressionRoot` for the latest available datum matching the given source ID, or `null` if not available.

22.4 Expression examples¶

Assuming a datum sample with properties like the following:

Property	Value
`current`	`7.6`
`voltage`	`240.1`
`status`	`Error`

Then here are some example expressions and the results they would produce:

Expression	Result	Comment
`voltage * current`	`1824.76`	Simple multiplication of two properties.
`props['voltage'] * props['current']`	`1824.76`	Another way to write the previous expression. Can be useful if the property names contain non-alphanumeric characters, like spaces.
`has('frequency') ? 1 : null`	`null`	Uses the `?:` if/then/else operator to evaluate to `null` because the `frequency` property is not available. When an expression evaluates to `null` then no property will be added to the output samples.
`current > 7 or voltage > 245 ? 1 : null`	`1`	Uses comparison and logic operators to evaluate to `1` because `current` is greater than `7`.
`voltage * currrent * (hasLatest('battery') ? 1.0 - latest('battery')['soc'] : 1)`	`364.952`	Assuming a `battery` datum with a `soc` property value of `0.8` then the expression resolves to `7.6 * 241.0 * (1.0 - 0.8)`.