Lookup Maps

A lookup map is a named, in-memory key-value store that can be referenced from instance attribute expressions and pipeline stages. It is populated from a table-like format (an array of JSON objects, or rows), but is surfaced and accessed as a map/object: each row is converted into an entry keyed by its Primary Key value. Lookup map values are stored in memory and enable quick access for data purposes. Depending on the source type, a lookup map is either fixed at configuration time or refreshed periodically by a backing pipeline.

Configuration Settings

These settings apply to every lookup map regardless of source type.

Setting	Description
Name	Unique identifier used to reference the lookup map in expressions and stage configuration.
Description	Free-text description displayed in the UI.
Group	Logical grouping label for organising lookup maps in the list view.
Tags	One or more tags for filtering.
Source Type	Determines how the lookup map is populated. Either Dynamic or Static.
Primary Key	The property present on every row that uniquely identifies it. Its value is used as the lookup key when referencing a specific row.

Source Types

Dynamic

A dynamic lookup map is populated by executing a backing pipeline. The lookup map is populated on first access and can be refreshed on a schedule via the expiration interval.

Setting	Description
Backing Pipeline	The pipeline responsible for populating the lookup map. Must return an array of JSON objects, where each object is a row. This array is only the population format; the resulting lookup map is stored and accessed as a map/object.
Expiration Interval	How long cached entries remain valid before the next access triggers a refresh. Set to 0 (zero) to populate once and never refresh. Supports milliseconds, seconds, minutes, hours, and days.

Populating Dynamic Lookup Map

When a lookup map is being fetched for the first time or the lookup map has expired due to the expiration interval, the Backing Pipeline will be called to refresh the lookup map. Any parameters configured on the backing pipeline reference will be passed to the pipeline call.

The pipeline must return an array of JSON objects. Each object in the array becomes a row: the value of the row’s Primary Key property becomes the lookup key, and the entire row object becomes the stored value for that key. The array returned by the pipeline is converted into a map at population time; it is not retained as an array.

Static

A static lookup map is defined entirely in configuration. Entries are loaded once on first access and never refreshed.

Setting	Description
Definition	A JSON array of objects, where each object is a row. Must contain at least one object, and every object must include the configured Primary Key property. This array is only the population format; the resulting lookup map is stored and accessed as a map/object.

Example definition:

[
  {
    "asset_id": "MCH-001",
    "site_id": "SITE-04",
    "machine_type": "CNC Milling Machine",
    "area": "Machining",
    "status": "Running"
  },
  {
    "asset_id": "MCH-002",
    "site_id": "SITE-04",
    "machine_type": "Conveyor",
    "area": "Packaging",
    "status": "Running"
  },
  {
    "asset_id": "MCH-003",
    "site_id": "SITE-04",
    "machine_type": "Injection Molding Machine",
    "area": "Molding",
    "status": "Down - Maintenance"
  }
]

With Primary Key set to asset_id, this array is converted into a lookup map with three entries, keyed by MCH-001, MCH-002, and MCH-003.

Referencing Lookup Maps

Instance Attribute Expressions

Lookup maps can be referenced in instance attribute expressions using the LookupMap reference type. The reference resolves to the full lookup map object (not the original array used to populate it), and dot-notation paths can be used to reach a specific entry (by its Primary Key value) or a nested field within that entry.

Reference the entire lookup map as an object:

{{LookupMap.MyLookupMap}}

Reference a specific entry by its key:

{{LookupMap.MyLookupMap.MCH-001}}

{{LookupMap.MyLookupMap}}["MCH-001"]

Reference a nested field within an entry:

{{LookupMap.MyLookupMap.MCH-001.status}}

{{LookupMap.MyLookupMap}}["MCH-001"]["status"]

Pipeline Merge Read Stage

The Merge Read stage reads values from one or more sources and merges them into a single output object. This makes it straightforward to populate pipeline events with lookup data. This data can later be used for dynamically looking up values in the lookup data. For example, joining a device reading with a static asset table or a dynamically refreshed calibration table.

Viewing Current Values

The Values tab on a lookup map’s detail page shows the current in-memory map as a searchable table, with one column per field and one row per entry. Both column values and entry keys are searchable. A refresh button re-fetches the current state from the runtime.

Constraints and Limitations

A dynamic lookup map’s backing pipeline cannot reference any lookup map.
- This avoids recursive loops when trying to populate lookup maps.
Every row must include the configured Primary Key property.
Lookup map values are stored in memory only; there is no persistence across restarts. On startup, a dynamic lookup map will be re-populated on its first access.