domain-tree-entities

domain-tree-entities decodes raw capture protobuf bytes and folds every observation into one current-state node per Entity. One node replaces a hydrate, fold and merge chain.

The node reads the bytes an input node stored as agnostic-input and never materialises the flat per-tick record list. Each entity node carries its id, name, the latest value per component type, and two time-ordered histories: health_history and position_history. Downstream nodes such as json-filter or system-arbex-js read those histories directly.

It is not a dashboard payload. The output is plain JSON for transform and insight nodes, not a $heat-dataservice envelope.

When to use

Use this node when a session template needs the current state and history of many entities from a large capture, and a hydrated flat record stream would be too big. Use it in place of hydrate-protobuf-v2 followed by hand-written folding.

Do not use it when you need the raw per-tick records themselves. hydrate-protobuf-v2 keeps every record.

Pipeline position

input-node (agnostic-input) -> domain-tree-entities -> json-filter -> system-arbex-js

The node accepts multiple parents. It fetches every output of every parent and folds them into the same entity tree, keyed by entity id.

Configuration

Configuration is optional.

Output

One JSON object with an entities array. Field names below are illustrative values.

{
  "entities": [
    {
      "id": "487",
      "name": "target-58",
      "first_seen_ms": 1777379654100,
      "last_seen_ms": 1777384607247,
      "components": {
        "health_data": { "current_health": 0.0 },
        "world_position": { "latitude": 53.462, "longitude": 8.384, "heading": -184.5 }
      },
      "health_history": [
        { "time_ms": 1777379654100, "current_health": 100.0 },
        { "time_ms": 1777384607247, "current_health": 0.0 }
      ],
      "position_history": [
        { "time_ms": 1777379654100, "latitude": 53.462, "longitude": 8.384, "heading": -184.5, "utm_eastings": 1002340, "utm_northings": -3 }
      ]
    }
  ]
}

Fold rules:

• components only updates from an observation that is the newest seen so far for that entity. An older chunk arriving late cannot overwrite newer state.
• health_history is sorted by time and deduplicated on value change after every observation is folded.
• position_history is sorted by time and deduplicated on identical latitude and longitude pairs. A stationary entity has one point.
• A current_health of zero and a missing value are folded the same way, as 0.0.

The output is written as a node output to the configured data source.

Limitations

• Entities are merged by id. Combining captures from unrelated scenarios conflates any entities that share an id.
• Raw chunks may arrive out of time order. The node handles this, but it must read every parent output before it can finalise histories.
• The node fails when no data source can be resolved, either from dataSourceName or from the runner default store.

Related

• domain-tree-hwio folds the hardware event bus into current state.
• domain-tree-hwio-events keeps the full hardware event history.
• hydrate-protobuf-v2 emits the flat record list when you need every tick.
• json-filter narrows the tree to the entities a widget needs.

HEAT documentation team. Last updated 2 October 2026.