Skip to content

23. Join Datum Filter

The Join Datum Filter provides a way to merge the properties of multiple datum streams into a new derived datum stream.

This filter is provided by the Standard Datum Filters plugin.

23.1 Settings

Join filter component 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.
Output Source ID The source ID of the merged datum stream. Placeholders are allowed.
Coalesce Threshold When 2 or more then wait until datum from this many different source IDs have been encountered before generating an output datum. Once a coalesced datum has been generated the tracking of input sources resets and another datum will only be generated after the threshold is met again. If 1 or less, then generate output datum for all input datum.
Swallow Input If enabled, then filter out input datum after merging. Otherwise leave the input datum as-is.
Source Property Mappings A list of source IDs with associated property name templates to rename the properties with. Each template must contain a {p} parameter which will be replaced by the property names merged from datum encountered with the associated source ID. For example {p}_s1 would map an input property watts to watts_s1.

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

23.2 Source Property Mappings settings

Each source property mapping configuration contains the following settings:

Setting Description
Source ID A source ID pattern to apply the associated Mapping to. Any capture groups (parts of the pattern between () groups) are provided to the Mapping template.
Mapping A property name template with a {p} parameter for an input property name to be mapped to a merged (output) property name. Pattern capture groups from Source ID are available starting with {1}. For example {p}_s1 would map an input property watts to watts_s1.

Unmapped properties are copied

If a matching source property mapping does not exist for an input datum source ID then the property names of that datum are used as-is.

23.2.1 Source mapping examples

The Source ID pattern can define capture groups that will be provided to the Mapping template as numbered parameters, starting with {1}. For example, assuming an input datum property watts, then:

Datum Source ID Source ID Pattern Mapping Result
/power/main /power/ {p}_main watts_main
/power/1 /power/(\d+)$ {p}_s{1} watts_s1
/power/2 /power/(\d+)$ {p}_s{1} watts_s2
/solar/1 /(\w+)/(\d+)$ {p}_{1}{2} watts_solar1

To help visualize property mapping with a more complete example, let's imagine we have some datum streams being collected and the most recent datum from each look like this:

/meter/1 /meter/2 /solar/1 
{
  "watts": 3213,
}
 
{
  "watts": -842,
}
 
{
  "watts"  : 4055,
  "current": 16.89583
}

Here are some examples of how some source mapping expressions could be defined, including how multiple mappings can be used at once:

Source ID Patterns Mappings Result
/(\w+)/(\d+) {1}_{p}{2} 
{
  "power_watts1"  : 3213,
  "power_watts2"  : -842,
  "solar_watts1"  : 4055,
  "solar_current" : 16.89583
}
  1. /power/(\d+)
  2. /solar/1
  1. {p}_{1}
  2. {p}
 
{
  "watts_1"  : 3213,
  "watts_2"  : -842,
  "watts"    : 4055,
  "current"  : 16.89583
}