Shape your first ontology

Goal

A first slice of your domain structured so it persists across runs. Done means three things exist and you know which is which: a versioned definition, build logic inside a plan, and inspectable runtime state with provenance.

Image: the three layers side by side — definition editor, plan with mapping steps, runtime browser with records and provenance.

Steps

1. Start small and connected: one synced source, one slice of the domain (customers and their orders — not the whole business).
2. Open the Ontology app and define the model:
   • Entity types: the kinds of things that exist (customers, orders, accounts) with their properties.
   • Relationships: how entities connect (a customer places an order, an account renews).
   • Identifiers: what makes each entity the same entity across systems — order id, account email, whatever is stable.
   • Constraints: the rules that keep the model honest (an order has exactly one customer, amounts are never negative).
3. Save the definition as a versioned asset. It branches, diffs, and rolls back like anything else under version control — because a model change is a decision worth reviewing, not a silent edit.

Image: definition editor with entity types, one relationship, and a version history entry.

4. Build the recipe in Pipeline Studio, not in the ontology editor. Mapping belongs in plans: add the steps that read source records, map fields onto entity properties, derive relationships, and resolve identity (matching "Acme Inc" to "Acme, Inc." before writing, so you get one customer instead of two).
5. Choose the write behavior deliberately: create new instances, update existing ones, or upsert — and what happens on conflict. Identity plus upsert rules decide whether reruns enrich your state or duplicate it.
6. Run the plan and inspect the runtime in the browser surface: entity instances, relationship instances, provenance back to source records, and freshness. The runtime is operational state, not the model — look, do not hand-edit.
7. Correct through the loop, not in the tables. Fix the definition, the mapping, or the source data, then rerun. Direct runtime edits bypass provenance and teach future runs nothing.

Image: runtime browser showing an entity, its relationships, and the provenance trail to source records and the run that built it.

When the model fights back

• Duplicates after reruns: identity rules are too weak or the identifier is unstable. Strengthen the identifier before touching the mapping.
• Relationships point nowhere: one side's identity failed to resolve. Check the mapping for that side first.
• Runtime looks right but the definition drifted: someone edited around the model instead of in it. Bring the change back into the definition and version it.

What good looks like

• Small and correct: a handful of trusted types over dozens of hopeful ones.
• Every instance traces to source records and the run that built it.
• A colleague reads the definition and recognizes your business.
• Reruns enrich state instead of duplicating it.

Next

• Predict from the state: Get your first forecast.
• Vocabulary questions: Concepts.