Knowledge Graph How-to

Configure your solution’s data foundation to build a knowledge graph

How-to Guides → The Four Pillars How-to → Data Foundation How-to → Unified Namespace How-to → Model Relations How-to

The example

A two-equipment water-treatment line:

Plant1/Pump_P1   --(FeedsInto)-->   Plant1/Tank_T1

Pump_P1 fills Tank_T1. Each tag carries live process variables. You will add a typed graph relation between them and, optionally, a /Attr sibling carrying static metadata. End state: a runnable solution and a Knowledge Graph that renders the relation visually.

Prerequisites

• A solution open in the Designer with the Unified Namespace module visible.
• Familiarity with creating UserTypes and Tags — see Unified Namespace How-to.

Step 1 — Create the UserTypes

Two UDTs. The interesting member is FeedsInto on PumpType: declared with Type = Reference, it becomes the graph edge.

PumpType

TankType

Create both via Unified Namespace → UserTypes → New, then add the members in the grid.

For the canonical member-column definitions (every column, every constraint), see UNS UserTypes Reference.

Step 2 — Wire the relation via StartValue

A Reference UDT member needs two fields to declare a graph edge:

In JSON form (for write_objects or copy-paste into a row):

{
  "Name": "FeedsInto",
  "Type": "Reference",
  "Parameters": "TankType",
  "StartValue": "Plant1/Tank_T1"
}

When the runtime starts, every PumpType instance gets its FeedsInto.Link resolved to Plant1/Tank_T1 automatically. The FrameworX object model now has a typed edge from Pump_P1 to Tank_T1.

Step 3 — (Optional) Add the /Attr metadata sibling

The /Attr dual-shape pattern stores static, design-sheet-style metadata on a sibling tag — separate from the live equipment tag. The naked tag carries dynamic process variables; the /Attr sibling carries literals like Manufacturer, ModelNumber, InstallationDate.

When to use which shape:

For Pump_P1 to carry both live process data AND nameplate metadata, declare a second UDT:

PumpType_Attr

Then create a sibling Tag at Plant1/Pump_P1/Attr of type PumpType_Attr (see Step 4).

For the full dual-shape rationale and the OWL/RDF round-trip semantics, see Industrial Ontology Integration How-to — sections "Two paradigms" and "FrameworX architecture and ontology alignment".

Step 4 — Create the instance Tags

In Unified Namespace → Asset Tree, create the folder Plant1 and add three tags inside it:

Either:

• right-click the Plant1 folder → New Tag, set the Type to the UDT, OR
• paste a row into the Tags grid with the Name and Type columns set.

The Asset Tree auto-creates the folder hierarchy from the slashes in the tag path.

Step 5 — Verify in the runtime

Start the runtime (F5). With the configuration above, the FrameworX object model now exposes:

@Tag.Plant1/Pump_P1                      <- PumpType instance (live)
@Tag.Plant1/Pump_P1.Flow                 <- Double, live
@Tag.Plant1/Pump_P1.Status               <- Text, live
@Tag.Plant1/Pump_P1.FeedsInto            <- Reference -> Tank_T1
@Tag.Plant1/Pump_P1.FeedsInto.Link       <- "Plant1/Tank_T1"

@Tag.Plant1/Pump_P1/Attr                 <- PumpType_Attr instance (static, optional)
@Tag.Plant1/Pump_P1/Attr.Manufacturer    <- "Grundfos"

@Tag.Plant1/Tank_T1                      <- TankType instance (live)
@Tag.Plant1/Tank_T1.Level                <- Double, live
@Tag.Plant1/Tank_T1.Status               <- Text, live

Quick sanity check from a Script or the runtime monitor:

// Read the resolved target through the Reference
string target = @Tag.Plant1/Pump_P1.FeedsInto.Link;
// Expected: "Plant1/Tank_T1"

// Read a value of the target tag through the Reference
double level = @Tag.Plant1/Pump_P1.FeedsInto.Value;   // routed to Plant1/Tank_T1

For the full Reference-tag runtime semantics, see UNS Tags Reference → Reference Type.

Step 6 — Visualize with the Knowledge Graph control

1. Open Unified Namespace → Asset Tree. Click the Knowledge Graph button at the top of the tree. This regenerates SolutionSettings.KnowledgeGraphSource from the current UDT + Tag + relation state.
2. Open or create a Display. From the Components Panel → Charts, drop Knowledge Graph onto the canvas.
3. In the control's Properties panel:
   • Bind Selected node path to a Tag of type Text (for example Tag.UI.SelectedNodePath). The control writes the clicked node's full UNS path (dot notation, e.g. Plant1.Tank_T1) into that Tag.
   • Bind Selected node type to a Tag of type Text (for example Tag.UI.SelectedNodeType). The control writes the clicked node's UserType name (e.g. TankType) into that Tag.
4. Run the Display. Clicking a node updates the two bound Tags. Wire those Tags to a ChildDisplay source, a Trend Chart, or any other control to drive type-aware drill-down.

The expected render for this example:

   +----------+   FeedsInto    +----------+
   | Pump_P1  | -------------> | Tank_T1  |
   | PumpType |                | TankType |
   +----------+                +----------+

For control configuration depth — render modes, source regenerators, HTML5 / OpenSilver parity, design-time preview semantics — see KnowledgeGraph Control Reference.

What this enables

Once the UNS carries Reference edges (and, optionally, /Attr metadata siblings), the same three building blocks — Reference members, StartValue, dual-shape — unlock four capabilities:

• Visualize the plant graph with the Knowledge Graph Display control (Step 6).
• Ground AI queries — the Local AI assistant walks Reference edges to answer questions like "what feeds into this tank?" or "trace upstream of Pump_P1".
• Export to RDF / OWL / JSON-LD / Turtle / N-Triples — see Export your UNS to RDF/OWL/GraphDB. The /Attr suffix is stripped on export so OWL entity IRIs match the source ontology.
• Re-import enriched ontologies from external authoring tools via Industrial Ontology Integration How-to, with the SourceIri column providing the join key for diff and overlay.

Troubleshooting

Reference member shows no value at runtime. Confirm Parameters is set to the target UserType name (case-sensitive), StartValue is the path of an existing Tag, and the target's UserType matches Parameters (or a subclass). The target must exist when the runtime starts; references to missing tags resolve to null.

Knowledge Graph control shows no edges. Click the Knowledge Graph button on the Asset Tree to regenerate KnowledgeGraphSource, or invoke TK.GenerateUnsVisual() from a Script. Edits to UDTs or Tags only refresh the source on the next regeneration; auto-refresh applies on subsequent renders.

Multiple PumpType instances all feed the same Tank. That is expected — UDT-level StartValue is the shared default. To point one instance elsewhere, set the Reference target on that specific tag; the per-instance value overlays the type default for that instance only. See UNS Asset Tree Reference → troubleshooting.

OWL round-trip drops the relation. If you used the ontology dual-shape, the Reference must target the identity-bearing node — the /Attr sibling. The exporter strips the /Attr suffix so the OWL IRI is clean. For plain equipment with no /Attr sibling, target the equipment tag itself. See Industrial Ontology Integration How-to.

See also

• Unified Namespace How-to — basic UNS configuration (prerequisite).
• UNS UserTypes Reference — UDT member-column definitions.
• UNS Tags Reference — Reference Type runtime semantics; ontology columns (Labels, SourceIri, Attributes).
• UNS Asset Tree Reference — dual-shape folder layout; per-instance StartValue.
• Industrial Ontology Integration How-to — standards coverage; the "Two paradigms" section.
• KnowledgeGraph Control Reference — control properties, source regenerators, render modes.
• Local AI — AI grounding on the UNS graph.
• LocalAI KnowledgeGraph Demo — reference solution exercising every column.
• RDF Triples and the Industrial Ontology Foundry (IOF) — the triples model behind the round-trip.

In this section...