Ontology Modeler workflow overview
Where ontology sits in portal as a first-class surface, which two menus the modeler lives in (Modeling and Graph Explorer), and how it connects to the analyst and engineer surfaces — all in a single table.
Analysts draw screens on top of data that already exists. Engineers are responsible for how that data got there. Between them, the ontology modeler defines what those datasets mean to one another — that is, the graph of entities and relations. In portal this work happens on a separate first-class surface.
Ontology's place in the sidebar — its own first-class section
In the left sidebar, separately from the Applications section, there is an ONTOLOGY section containing two menus.
- Modeling (the modeling builder) — Where you define and edit entities and relations. Toggle between a graph view with nodes and edges on a canvas, or a table view for bulk management.
- Graph Explorer — Visually explore the instance data landed on top of the defined model. Cypher queries, label clicks, and double-click neighbor expansion all happen here.
This hierarchical separation enforces two consequences.
- Entities and relations do not appear as leaves in the collection tree. Ontology resources are managed only from pages inside the ONTOLOGY section.
- One collection = one ontology scope. Creating a collection automatically creates the corresponding ontology scope, and creating an entity or relation requires specifying the owning collection (
collection_id). Missing it returns 422.
The sidebar hierarchy itself enforces the mental model: "ontology is not a tool, it's the semantic layer of the data."
The three building blocks of ontology
Every lesson in this Path keeps returning to these three.
- Entity — An abstraction of a real-world object (customer, product, order, machine, sensor). It sits as a semantic layer on top of a backing dataset.
- Relationship — The connection between two entities (customer purchases a product, sensor reads a machine). It has direction and a type (
PURCHASED,IOT_reads_from) and is stored in the graph database. - Schema metadata — Each entity and relation has Identity Keys (the instance's unique identifier) and a Display Column (the primary UI label). When either is empty, nodes appear unnamed in the Graph explorer, and a pipeline's Entity I/O fails its payload validation.
Mapping to familiar vocabulary (one-time only)
If you've worked the same flow with ER modeling, Neo4j, or RDF, keep the table below in your head for the first 30 minutes — that's enough to start reading portal. From lesson 02 on, we use portal's vocabulary only.
| Familiar term | Corresponding term in portal |
|---|---|
| ER model entity | Entity |
| Primary key (PK) | Identity Keys |
| Human-readable label column | Display Column |
| ER relationship · Neo4j relationship type | Relationship — source · target · type |
Neo4j :Label | Entity name (name) |
| Graph DB instance | A single node visible in the Graph explorer |
| Cypher | The query editor at the bottom of the Graph explorer (used as-is) |
Two points worth flagging against the existing vocabulary:
- Model and instance surfaces are separated. Modeling is class definition; Graph Explorer is instance exploration. You'll move between the two screens often.
- No sink UI. Once mapping is done, the backend infrastructure lands instances into the graph database automatically. The previous version's EntitySink / RelationSink buttons were removed.
Two domain examples — a small graph and a larger one
The lesson bodies in this Path alternate between two scenarios.
- Manufacturing IoT — small graph (3 + 2): three entities
IOT_Machine,IOT_Sensor,IOT_MaintenanceEvent, and two relationsIOT_reads_from(sensor → machine) andIOT_triggers(machine → maintenance event). The smallest semantic unit that fits in one screen. - Retail supply chain — larger graph (4 + 3): four entities
RI_Product,RI_Branch,RI_Region,RI_Supplier, and three relationsRI_STOCKED_AT(product → branch),RI_LOCATED_IN(branch → region),RI_SUPPLIED_BY(product → supplier). Shows relation diversity and cardinality differences in one view.
Seeing the small and the larger graph alternately across lessons builds your sense of where to stop drawing when you model your own domain.
Responsibility boundary with analyst and engineer
For the three roles to share one portal without stepping on each other, you need an explicit handshake.
| Responsibility | Usually whose job |
|---|---|
| Ingest data from external systems and land it as a dataset | Engineer |
| Define the semantic layer (entities, relations) on top of datasets | Modeler |
| Decide Identity Keys, Display Column, and cardinality | Modeler |
| Map dataset columns to entity attributes | Modeler (in the same seat as the engineer) |
| Build widgets and dashboards on top of the graph | Analyst |
| Trace governance and audit traces in the Graph explorer | Modeler + Analyst |
Depending on team size, one person can hold two or all three roles. This Path runs every lesson from the modeler's seat: which surface, and what to decide on it.
What this lesson teaches
- The two menus inside the ONTOLOGY section (Modeling, Graph Explorer) and the question each answers
- The three building blocks: entity, relationship, schema metadata
- The mapping between familiar vocabulary (ER, Neo4j, Cypher) and portal vocabulary
- The "one collection = one ontology scope" rule, and the boundary with analyst and engineer
Next lesson
In the next lesson you'll enter the first surface — the Modeling builder — and define a single entity by hand. Name, alias, Identity Keys, Display Column, and the six attribute types all live in one place.