OntoBricks User Guide

Introduction

OntoBricks is a visual tool for designing ontologies, mapping them to Databricks tables, generating R2RML mappings, synchronizing data to a triple store, and exploring your graph viewer visually. This guide walks you through the complete workflow.

Prerequisites

Before starting, ensure you have:

• Access to a Databricks workspace
• Personal access token from Databricks
• SQL Warehouse ID
• Catalog and schema with tables to map

Settings: Lakehouse Health (Registry permissions)

The Settings → Lakehouse → Health tab validates whether the application principal has the Unity Catalog permissions required to operate on the saved Registry location (catalog.schema).

What Health checks

Health uses the Unity Catalog effective-permissions API on the configured Registry schema and evaluates this operational permission set:

• USE CATALOG
• USE SCHEMA
• CREATE TABLE
• CREATE VIEW
• SELECT
• MODIFY

ALL PRIVILEGES is expanded and treated as satisfying the full set. Inherited grants (for example from catalog-level assignments) are accepted.

Principal resolution

In Databricks Apps, Health checks permissions for DATABRICKS_CLIENT_ID. Outside Databricks Apps, it falls back to the authenticated Databricks user. The resolved principal is shown in the Health panel.

Operational status semantics

• Operational means all six required permissions are granted.
• Missing permissions means at least one required permission is not granted.
• API/auth/network issues are shown as diagnostic Health results and do not represent domain data problems.

What Health does not check

The Health tab is intentionally domain-independent. It does not inspect:

• domain assets or Objects inventory
• R2RML VIEW existence or content
• data-table or inferred-table existence
• row counts
• SQL Warehouse state
• materialization mode

Use the Lakehouse → Objects tab for asset inventory and object-level visibility. Health answers only one question: "Can this principal operate on the configured Registry schema?"

Application Workflow

OntoBricks follows a 3-step workflow:

1. Design Ontology → 2. Assign Data Sources → 3. Knowledge Graph (Sync & Explore)

Step 1: Design Ontology

Navigate to the Ontology page by clicking "Ontology" in the navigation bar.

Option A: Visual Designer (Recommended)

Click Business Views in the sidebar to use the visual drag-and-drop interface.

Creating Entities

1. Click the + Add Entity button in the toolbar
2. A new entity box appears on the canvas
3. Edit the entity name by clicking on it
4. Add attributes using the + button on the entity
5. Move entities by dragging them around the canvas

Customizing Entities

Each entity supports:

• Icon: Click the icon button (🎨) to select an emoji
• Auto-Map Icons: In the Model view, click the smiley face button (😊) in the toolbar to automatically assign emoji icons to all entities that still have the default icon. This feature uses the domain's configured LLM serving endpoint to pick the most appropriate emoji for each entity name.
• Description: Click the description button (📝) to add notes
• Attributes: Add data properties directly on the entity

Creating Relationships

1. Click and drag from one entity's connector (○) to another
2. A relationship line is created between them
3. Edit the relationship name by clicking on the label
4. Add relationship attributes using the + button on the relationship

Creating Inheritance Links

Inheritance links represent class hierarchies (rdfs:subClassOf):

1. Click the △ (Inheritance) button in the toolbar to activate inheritance mode
2. Drag from a parent entity's connector to a child entity
3. A dotted line with a hollow arrow appears from parent to child
4. Child entities automatically inherit all attributes from the parent (displayed as read-only)
5. Click the inheritance arrow to reverse the direction if needed

Example: Create an "Employee" entity that inherits from "Person":

• Person has attributes: name, email
• Employee inherits name and email from Person, plus its own attributes: employeeId, salary

Relationship Direction

Each relationship has a direction button showing:

• → Forward: From source to target entity
• ← Reverse: From target to source entity
• ↔︎ Bidirectional: Both directions

Click the direction indicator to cycle through options.

Canvas Controls

• Zoom: Use the mouse wheel or zoom buttons
• Pan: Click and drag the background
• Auto Layout: Click the grid icon to organize entities
• Center: Click the center button to fit all entities in view
• Minimap: Toggle the minimap for navigation

Auto-Save

All changes in the Design view are automatically saved. You'll see a brief "Saving..." indicator when changes are persisted.

Option B: Form-Based Interface

Configure Basic Information

1. Click Information in the sidebar
2. Enter an Ontology Name (e.g., "MyOrganization")
   • Used in the URI and file naming
3. The Base URI is auto-generated from:
   • The Default Base URI Domain (from Settings)
   • The domain name
   • Format: {domain}/{DomainName}#
   • Example: https://databricks-ontology.com/MyOrganization#
   • Toggle the Custom switch on the Domain page to enter a custom URI

Add Classes (Entities)

1. Click Entities in the sidebar
2. Click Add Class button
3. Enter:
   • Name: Class identifier (e.g., "Person", "Department")
   • Label: Human-readable name (optional)
   • Icon: Select an emoji/icon for visualization
   • Description: Brief description of the entity
4. Add Attributes: Use the attributes section to add data properties
5. Click Apply to write the class into the session

Example Classes:

• 👤 Person (represents people in your organization)
• 🏢 Department (organizational units)
• 📋 Project (work projects)

Add Relationships (Object Properties)

1. Click Relationships in the sidebar
2. Click Add Property button
3. Enter:
   • Name: Relationship identifier (e.g., "worksIn", "manages")
   • Domain: Select source entity from dropdown
   • Range: Select target entity from dropdown
   • Direction: Choose Forward, Reverse, or Bidirectional
4. Add Attributes: Add relationship properties if needed
5. Click Apply to write the relationship into the session

Example Relationships:

• worksIn (Person → Department)
• manages (Person → Project)
• collaboratesWith (Person ↔︎ Person)

Advanced Features

OntoBricks provides advanced ontology features under the Advanced section in the sidebar.

SWRL Rules (Graphical Editor)

Click Business Rules in the sidebar to define inference rules using SWRL (Semantic Web Rule Language). OntoBricks provides a graphical D3-based editor for building rules visually.

1. Click Add Rule to open the fullscreen rule editor
2. The editor has two panes:
   • Left: Interactive D3 graph showing your ontology classes and relationships
   • Right: Rule builder with IF (antecedent) and THEN (consequent) atom lists
3. Building rules visually:
   • Right-click a class or relationship on the graph to open the context menu
   • Choose Add to IF or Add to THEN to add atoms
   • Variable names (e.g., ?x, ?y) are assigned automatically
   • The SWRL preview updates live as you add atoms
4. Advanced mode: Toggle the Advanced section to edit raw antecedent/consequent text directly
5. Enter a Rule Name and optional Description
6. Click Save Rule

Import/Export: Click the header SWRL button to open a modal (same pattern as Data Quality → SHACL). Refresh shows the current rules as OntoBricks SWRL text (# Rule: / optional # Description: / antecedent -> consequent). Export downloads a .swrl file; Import appends parsed rules to the existing list (duplicate names are allowed).

Example SWRL Rules:

Rule: InferGrandparent
Antecedent: Person(?x) ∧ hasParent(?x, ?y) ∧ hasParent(?y, ?z)
Consequent: hasGrandparent(?x, ?z)

Rule: InferManager
Antecedent: Person(?x) ∧ worksIn(?x, ?d) ∧ manages(?y, ?d)
Consequent: hasManager(?x, ?y)

Rules are compiled to Spark/Postgres SQL for execution in the Reasoning pipeline. The capability flags on GraphDBBackend reserve a slot for a future Cypher / Gremlin engine.

Expressions & Axioms

Click Expr. & Axioms in the sidebar to define OWL class expressions and axioms.

1. Click Add Axiom button
2. Select Axiom Type:
   • Class Relationships: Equivalent, Disjoint, Union, Intersection
   • Property Relationships: Inverse, Property Chain, Disjoint Properties
3. Configure subject, objects, and type-specific options
4. Click Save Axiom

Example Axioms:

Data Quality (SHACL Shapes)

Click Data Quality in the sidebar to define data quality rules using W3C SHACL (Shapes Constraint Language).

1. Click Add Shape to create a new data quality shape
2. Select a Category:

3. Select the Target Class and Property to constrain
4. Choose the SHACL Constraint Type (minCount, maxCount, pattern, datatype, class, hasValue, etc.)
5. Configure constraint-specific parameters
6. Optionally add conditions (conformance and consistency rules only) — see below
7. Set Severity (Violation, Warning, Info) and an optional Message
8. Click Save

Conditional rules (the IF block): a conformance or consistency rule can be guarded so it only applies to the instances matching a set of conditions — IF status = active AND amount > 1000, THEN email must match the pattern. Each condition is a property, an operator and a value, built the same way as a decision-table condition in Business Rules. The All / Any toggle combines the rows with AND or OR. Conditions may reference any attribute of the target entity, or a relationship with the exists / does not exist operators. A rule with no conditions applies to every instance, exactly as before.

Import/Export: Shapes can be exported as W3C-compliant SHACL Turtle and imported from existing SHACL files. A guarded rule is exported as its own node shape with a SHACL-AF sh:target [ a sh:SPARQLTarget ]. Conditions are not reconstructed on import: the constraint comes back unguarded and the import result reports how many rules lost their conditions.

Validation: Shapes are executed in the Knowledge Graph → Data Quality section. Every check is compiled to SQL and run against the triple-store VIEW, which the build creates whatever graph engine the domain uses, so a rule gives the same answer on Lakebase, Delta and Neo4j domains. The VIEW carries the triples mapped from your source tables; triples added by reasoning live in the graph store and are deliberately outside the scope of data quality. A numeric-range rule also reports a value that is not a number at all, since SHACL treats a value it cannot compare as a violation. A rule that cannot be compiled to SQL is listed with an info icon and no pass rate rather than counted as passing.

Dashboard Mapping

You can assign Databricks dashboards to entity types for embedded visualization in the Knowledge Graph:

1. Go to Ontology → Entities
2. Select an entity type (e.g., Customer, Meter)
3. In the entity details panel, find the Dashboard section
4. Click Assign to open the dashboard picker
5. Select a dashboard from your Databricks workspace
6. If the dashboard has parameters, map them to entity attributes:
   • Entity ID: Maps the parameter to the entity's unique identifier
   • Attribute Name: Maps the parameter to a specific entity attribute
7. Click Apply (writes into the session; publish the domain to persist)

Parameter Mapping: When a dashboard has filter parameters (e.g., customer_id, meter_id), you can map them to:

• __ID__: The entity's unique identifier (extracted from URI)
• Any attribute defined on the entity type

When viewing an entity in the Knowledge Graph visualization, the dashboard will be embedded with the correct parameter values.

Class Actions (Unity Catalog functions)

Beyond the linked dataset, an entity type can expose actions — Unity Catalog functions that operate on a single entity and can be run from the Graph Explorer or from an MCP client.

1. Go to Ontology → Entities and select an entity type
2. Open the External tab and find the Actions section
3. Click Add to open the function picker, then choose a catalog and schema
4. Pick a function and type a description — the description is what the LLM and the end user see, so make it explicit about what the action does
5. Click Apply (writes into the session; publish the domain to persist)

One-parameter contract: the selected Unity Catalog function must accept exactly one parameter — the ID of the entity to act on. OntoBricks passes the entity's local ID (extracted from its URI) automatically at invocation time. Functions with a different number of parameters are shown greyed out in the picker and cannot be selected.

Table-valued functions (RETURNS TABLE) are executed as SELECT * FROM fn('<id>') and their rows are rendered as a table; scalar functions are executed as SELECT fn('<id>') AS result and their value is shown as a single result.

In the Graph Explorer, actions appear both in the entity details panel and in the node right-click menu. Only functions declared on the entity's ontology class can be invoked — the server rejects anything else, so the ontology acts as the allow-list.

Virtual Attributes (computed on demand)

A virtual attribute is an attribute nobody maps. Instead of coming from a column, it is computed by a Unity Catalog function from the entity's ID, at the moment someone asks for it. Use one for a value that is a function of the entity rather than a fact stored about it: a live risk score, a current inventory position, a distance to the nearest depot.

The difference from an action is what it looks like, not what it runs. An action is a verb the user clicks; a virtual attribute is declared on the class like any other attribute and sits next to the mapped ones.

1. Go to Ontology → Entities and select an entity type
2. Open the Attributes tab and find the Virtual Attributes section
3. Click Add to open the function picker, then choose a catalog and schema
4. Pick a function — the picker shows what it returns
5. Fill in the description and, optionally, a display label per attribute
6. Click Apply (writes into the session; publish the domain to persist)

Picking a function creates one virtual attribute per returned column, named after the column and read from information_schema. A scalar function creates exactly one, named after the function. The same one-parameter contract as actions applies: the function must take exactly the entity's ID, and functions with any other signature are greyed out.

If a derived name is already used by a mapped or virtual attribute of the class, it is suffixed (score → score_2) and the UI tells you — the Graph Explorer and MCP render both families in one list, so the collision has to be settled here. Removal works per function, not per attribute: the attributes are the function's signature, so dropping one alone would make the column-to-attribute mapping ambiguous.

In the Graph Explorer, virtual attributes get their own section under Attributes, listed but empty, with a Compute button per function, a Compute all when there are several, and a Compute virtual attributes entry in the node right-click menu. Values stay cached for the page's lifetime so revisiting a node costs nothing; Recompute is the refresh. A function that fails reports its error inline and leaves the other functions' values alone.

Not queryable. Because a virtual attribute is never materialised, it takes no part in mappings, R2RML, the build, SHACL or data-quality checks — and it cannot be selected or filtered in SPARQL, GraphQL or a cohort. That is the trade for a value that is always current. Use a mapped attribute when you need to query it.

Option C: AI-Powered Wizard

Click Generate in the sidebar to generate an ontology automatically from your database schema using an LLM.

1. Select the LLM Endpoint (a Databricks Model Serving endpoint)
2. Choose which catalog/schema metadata to include
3. (Optional) Select uploaded Documents to enrich the generation
4. Write custom Guidelines or pick a Quick Template
5. Click Generate to create the ontology

Documents (PDF and other formats)

Documents uploaded under Domain → Documents feed the Wizard. Plain-text files (.txt, .md, .json, .csv, .xml) are read directly. Binary documents (.pdf, .docx, .pptx, images) are automatically converted to markdown using the Databricks ai_parse_document function, which runs on your configured SQL warehouse — so a warehouse must be configured and its identity must have read access to the documents volume. Without a SQL warehouse, binary documents are skipped and generation uses metadata, guidelines, and text documents only.

Quick Templates

The Wizard provides predefined guideline templates for common domains (CRM, E-Commerce, IoT, Healthcare, Energy, etc.). Click a template button to pre-fill the guidelines textarea.

Templates are defined in src/shared/config/constants.py under WIZARD_TEMPLATES and served to the frontend via the GET /ontology/wizard/templates endpoint. To add a new template, add an entry to the dictionary:

WIZARD_TEMPLATES = {
    "my_domain": {
        "label": "My Domain",
        "icon": "star",            # Bootstrap Icons name (without "bi-")
        "guidelines": "Generate an ontology for ...",
    },
    # ... existing templates
}

The button will appear automatically in the Wizard UI — no HTML changes needed.

Option D: Import Industry-Standard Ontologies

Click Import in the sidebar to load ontologies from files or industry standards:

• OWL: Import an OWL file from your local machine or Unity Catalog
• RDFS: Import an RDFS schema file
• FIBO: Import the Financial Industry Business Ontology (EDM Council) — select domains such as Foundations, Business Entities, Securities, etc.
• CDISC: Import Clinical Data Interchange Standards (PhUSE) — select SDTM, CDASH, SEND, or ADaM modules
• IOF: Import the Industrial Ontologies Foundry (OAGi) — select Core, Maintenance, or Supply Chain domains for digital manufacturing ontologies

Industry-standard modules are fetched directly from their official servers/repositories and merged automatically. The Core/Foundation module is always included when selecting domain-specific modules.

Preview OWL Output

Click OWL in the sidebar to see the generated OWL in Turtle format.

Save Your Ontology

• Validate: Click to check for issues
• Save: Store to Unity Catalog Volume
• Load: Load an existing ontology from UC

Step 2: Map Data Sources (Mapping)

Navigate to the Mapping page by clicking "Mapping" in the navigation bar.

Note: You must have an ontology loaded before creating mappings. The "Ontology" indicator in the navbar should show a green checkmark.

Users with an Editor or Builder role on the current domain can browse Unity Catalog and import, update, or remove data sources. CAN_MANAGE is only required for shared application configuration such as SQL Warehouse selection.

Information (Sidebar)

Click Information in the sidebar to view the current mapping status:

• Summary of mapped vs unmapped entities
• Summary of mapped vs unmapped relationships
• Count of mapped attributes across all entities
• Overall completion percentage and status

Visual Mapping Designer

Click Designer in the sidebar to use the visual mapping interface. This view provides an interactive force-directed graph of your ontology with color-coded mapping status:

• Green nodes: Fully assigned entities (all attributes mapped)
• Orange nodes: Partially assigned entities (some attributes missing)
• Red nodes: Unassigned entities

Mapping Entities

1. Click on any entity node in the graph to open the mapping panel
2. The panel has three tabs:
   • Wizard: AI-powered SQL generation using your LLM endpoint and table metadata
   • SQL: Direct SQL editing
   • Mapping: Interactive column-mapping grid with data preview
3. For already-assigned entities, the preview query runs automatically on first access. Switching away and back reuses the preview while the entity SQL and row limit remain unchanged; use Refresh to run it again explicitly.
4. For new entities, the Wizard tab opens by default — describe your data and click Generate to create SQL
5. In the Mapping tab:
   • Click column headers to assign them as ID, Label, or specific attributes
   • Use the Limit input to control how many preview rows are shown
   • Click Refresh to re-run the query with the current limit
6. Click Apply in the panel footer (writes into the session; publish the domain to persist)

Note: The SQL query is stored without a LIMIT clause. The preview limit only affects the grid display and is not part of the applied mapping. Clicking the empty canvas closes an unchanged mapping panel without saving or refreshing the designer.

Example SQL Query:

SELECT person_id, name, email, salary
FROM main.default.person

Mapping Relationships

1. Click on any relationship line in the graph
2. The same panel opens with Wizard, SQL, and Mapping tabs
3. Assign Source ID and Target ID columns from query results
4. Click Apply

Writing SQL Queries for Relationships

Your SQL query should return columns identifying source and target entities.

Example 1: Simple Foreign Key

SELECT person_id, department_id 
FROM main.default.person
WHERE department_id IS NOT NULL

Example 2: Join/Bridge Table

SELECT pd.person_id, pd.department_id
FROM main.default.person_department pd

Example 3: Self-referential Relationship

SELECT person1_id as source_id, person2_id as target_id
FROM main.default.person_collaboration

Manual Mapping (Sidebar)

Click Manual in the sidebar for a tree-based view of all entities and relationships organized by mapping status. The bottom panel shares the same UI and functionality as the Designer view panel — clicking an item opens the same Wizard/SQL/Mapping tabs.

Excluding and Including Attributes

By default every ontology attribute is included in the mapping. The Status tab of the bottom panel shows an attributes table where each row has a checkbox:

• Checked (✓) — attribute is included; it must be assigned to a SQL column and will be emitted in the R2RML export.
• Unchecked — attribute is excluded; it is shown with strikethrough, skipped in gap reporting, never mapped by Auto-Map, and not emitted in the R2RML export.

To exclude attributes:

1. Open an entity panel (click a node on the canvas).
2. Select the Status tab.
3. Uncheck any attributes you do not want to map.
4. Click Apply — exclusions are written into the session immediately.

Two bulk-action buttons are available at the top of the attributes table:

• Exclude all / Include all — toggles all attributes at once. When all attributes are currently included the button reads Exclude all; once any are excluded it switches to Include all so you can restore them in one click.
• Exclude unmapped — excludes only attributes that have no column assignment yet, leaving already-mapped attributes untouched.

Tip: Exclusions survive an Unmap / re-map cycle. If you right-click an entity and choose Unmap, the SQL and column assignments are cleared but the attribute checkboxes stay as you left them. Auto-Map also respects exclusions — it will never map or re-include an excluded attribute.

Effect on the canvas: An entity node is green only when every included attribute has a column assigned. Excluded attributes do not count towards the orange "attributes missing" indicator.

Effect on the Auto-Map KPI page: The Attribute gauge and tile count only included attributes. If you have 14 attributes and exclude 1, the tile shows 13 / 13 (100%) rather than 13 / 14.

Auto-Map (Sidebar)

Click Auto-Map in the sidebar to batch-assign all unmapped entities and relationships:

1. The page shows counts of unassigned entities and relationships, including how many are excluded (· N excl.).
2. If tables or columns are missing COMMENT descriptions, a metadata quality warning is displayed with a collapsible list and a link to the Domain → Metadata editor. Poor descriptions reduce LLM mapping accuracy.
3. Click Start Auto-Map to launch an asynchronous task.
4. Progress is tracked with a progress bar — you can navigate away and return later.
5. Results are displayed in a report table showing success/failure per item.

Live agent activity: while the run is in progress, expand Agent activity log in the progress overlay to watch the agent work item by item — which tool it called, what it got back, and how long each step took. The log refreshes roughly every 1.5 seconds and keeps growing until the run ends, so a long auto-map is no longer a silent progress bar.

Cancelling a run: Cancel stops the agent at the next item boundary instead of at the end of the batch. Everything already mapped is kept, and the run is recorded as cancelled.

Execution report in the Audit Trail: every auto-map run — completed, failed, or cancelled — writes an Auto-mapping agent run entry to Domain → Audit trail, with the status, the entity/relationship counts, the duration, and the full ordered step list the overlay showed live. Like the individual mapping change entries, it appears in the Audit Trail once the domain version has been saved to the registry.

Re-Assign Missing Attributes: If some entities are assigned but have incomplete attribute mappings, a third card appears showing the count and a Re-Assign Missing Attributes button. This re-runs auto-mapping only for those specific entities to fill in the missing included attribute mappings (excluded attributes are ignored).

Validate Your Mappings

Mapping validation checks:

• All ontology classes have entity mappings
• All object properties have relationship mappings
• All included attributes of mapped entities are assigned to columns (excluded attributes are ignored)
• No missing or incomplete mappings

A green checkmark appears in the navbar when all mappings are complete.

Source Schema Drift

A mapping can be perfectly well-formed and still be broken by a change made outside OntoBricks — a column renamed or dropped in the source table. The Mapping designer checks for this when it loads and flags it in three places:

• A ⚠ marker on affected entity nodes in the canvas; hover to see which columns are missing.
• A warning banner at the top of the entity or relationship panel, listing the bound columns that no longer exist upstream.
• A drifted badge and a schema drift row in Diagnostics, next to the existing checks.

These are advisory warnings, not errors: nothing about your mapping is invalid, the upstream table moved. Fix them by remapping the attribute to its new column or restoring the column in the source table.

Drift is only reported when the bound columns come straight from a table — a mapping whose SQL has an explicit SELECT list is validated against that projection instead, since its aliases are expected to differ from the table's own column names. Tables the app cannot read (missing, or no SELECT grant) are skipped rather than reported as fully dropped; the Diagnostics permission section covers those.

R2RML Output

The R2RML mapping output is available in the Domain section under R2RML. Navigate to Domain → R2RML to:

• View the automatically generated R2RML mapping in Turtle format
• Copy to clipboard
• Download as .ttl file

Step 3: Knowledge Graph (Sync & Explore)

Navigate to the Knowledge Graph page by clicking "Knowledge Graph" in the navigation bar (URL: /dtwin).

Note: You need both Ontology and Mapping loaded (green checkmarks in navbar). The Sync page shows a readiness status and disables actions until both are ready.

Build (Sidebar)

Click Build in the sidebar to manage your triple store:

• Readiness Status: Shows whether Ontology and mappings (including attribute mappings) are all complete
• Synchronize: Generates all triples from your mappings and writes them to the Delta view in Unity Catalog and to the configured Graph DB engine (Lakebase Postgres)
• Last Updated: When the table contains data, the status area displays the last modification date and time (for Delta from Unity Catalog metadata; for Lakebase from the Postgres count_triples + table metadata)

Storage kind (Lakehouse domains). On a Lakehouse domain the page names the kind of object …_data is, because the two materialization modes produce objects with the same name and very different behaviour. Next to the target FQN a badge reads either TABLE · materialized copy or VIEW · no data copy, and the page's subtitle, the note under the FQN, and the status card title all follow the same mode:

In both modes …_inferred stays a Delta table, so reasoning and cohort writes are unaffected.

Runs (Sidebar)

Click Runs in the sidebar (next to Build, in the Management group) to see the domain's run history. The page has two tabs, each with its own table, newest first — neither has a version filter, so both always span every version of the domain:

• Build runs (the tab shown first) — one row per synchronize (Build) run: ID, date & time, version, status, triple count, and a Details button.
• Analytics runs — one row per analysis launched from the Analytics page, with 11 columns: Date & Time, Scope, Version, Status, Nodes, Edges, Components, Avg Degree, Density, Duration, and Details. Scope shows the entity type(s) the run was filtered to, or All types. Version is shown per row because, with no filter, rows from different domain versions interleave in the same list. A failed run shows a red Failed badge and dashes in its metric columns instead of the zeros it stored internally — a run that errored out is not the same thing as a graph with zero nodes.

Click Details on an analytics row to open a modal with the full scope (entity-type local names plus their raw URIs), the graph metrics, the run duration, the background task ID, and any error text if the run failed.

Both tabs are filled when you open the section, whichever one is showing, so switching between them never waits on a fetch. The two load independently: if one fails, the other still renders normally and only the failing tab shows an inline error. The Refresh button above the tabs reloads both.

Every domain at once. This page is scoped to the domain you have loaded. From Settings → Automation → Runs (admin only) an admin sees the same two tabs across every domain in the registry, with a Domain column, a Domain filter that defaults to All domains, and page controls (25 / 50 / 100 rows) — cross-domain history is far too long to show in one list. Both pages read the same registry tables, so a run shows up in both.

Data Quality (Sidebar)

Click Data Quality in the sidebar to run SHACL-based quality checks against the triple store:

• Quality checks run asynchronously as a background task with progress tracking
• You can navigate away and return — the task resumes from where it left off
• Validates cardinality, value constraints, property characteristics, and global rules
• Shows pass/fail results with violation details
• Displays the generated SQL for each check

Explorer (Sidebar)

Click Explorer in the sidebar to explore triples as an interactive sigma.js WebGL-powered graph. Triple store data is automatically loaded when you navigate to this section:

Main Graph Area (left):

• Nodes: Entities (colored by class type with emoji icons in labels)
• Edges: Relationships between entities
• Labels: Entity labels from rdfs:label or mapped label column
• Hover: Highlights the hovered entity and its neighbors; dims unrelated nodes
• Click: Selects an entity and locks the highlight until another entity or the background is clicked
• Zoom: Scroll to zoom in/out
• Pan: Click and drag background
• Fit to View: Click the fullscreen button to fit all entities in view

Find & Filter:

• Find: Search for entities by label or URI — matching entities and their neighbors are highlighted and the camera zooms to focus on results
• Filters: Advanced filtering by entity type, field (label/URI), match type (contains, exact, starts with, ends with), with relationship depth control — rebuilds the graph with only matching triples

Entity Details Panel (right): When you click on an entity in the graph, the right panel shows:

• Entity Type: The ontology class (e.g., Person, Department) with icon
• Entity ID: The unique identifier
• Entity Label: The display name
• Mapped Attributes: All attributes defined in the mapping with their values
• Relationships: All incoming and outgoing relationships with clickable entity links for navigation
• Dashboard: If a dashboard is assigned to this entity type, a "View Dashboard" button appears

Dashboard Embedding: If an entity type has an assigned Databricks dashboard (configured in Ontology → Entities):

1. Click "View Dashboard" in the entity details panel
2. A modal opens with the embedded dashboard
3. Dashboard parameters are automatically populated from entity attributes
4. The dashboard displays data specific to the selected entity

Note: Empty entities (type URIs without data) are automatically filtered out.

Right-click on a node (Expand neighbours):

Right-click any entity node and pick Expand neighbours (N hops) to enrich the displayed graph in place — without re-running a full SPARQL query.

• The hop count follows the Depth slider in the right-pane filter panel (default 2).
• A small spinner appears in the top-right corner of the canvas while the request is running; the rest of the UI stays interactive.
• Newly added entities are merged with the existing graph, briefly ringed with a highlight, and the camera zooms to frame them.
• The same context menu still exposes the existing View Dashboard, Dataset preview, Actions, Bridges and Compute virtual attributes entries when configured for the entity's class.

Data Clusters:

The Graph Viewer includes a Data Clusters panel (in the View tab) for detecting communities in the graph:

1. Detect clusters (local): Runs the Louvain community detection algorithm client-side using Graphology on the currently displayed subgraph. Adjust the Resolution slider to control cluster granularity (higher = more clusters).
2. Full graph (backend): Sends a request to the server which loads the entire triple store into NetworkX and runs the selected algorithm (Louvain, Label Propagation, or Greedy Modularity) on the full dataset. Use this for large graphs that exceed the visible subgraph.
3. Color by cluster: Toggle to recolor nodes by their detected community instead of by entity type.
4. Collapse / Expand: Collapse clusters into super-nodes that show the cluster size and member count. Click a collapsed cluster super-node to see its members in the detail panel. Expand individual clusters or all at once.
5. Clear clusters: Reset all cluster assignments and return to the default visualization.

The cluster panel also displays:

• Total number of detected clusters
• A color-coded chip list of all clusters with their sizes
• Click a chip to toggle collapse/expand for that cluster

Analytics (Sidebar)

Click Analytics in the sidebar to compute and visualise centrality and structural metrics for the entities in your knowledge graph. Analytics always runs on a serverless Databricks Lakeflow job — there is no in-memory or SQL-pushdown fallback.

Because the job can take a while on large graphs, it runs asynchronously in the background. The last result is persisted in the registry (the graph_analytics table), so re-opening the Analytics page (or the Domain Validation cockpit) shows the previously computed result immediately without recomputing — a "Last computed …" line marks when it was produced.

Prerequisites. Three conditions must all be met before a run can start; the Analytics panel tells you which one is missing if any of them fails:

1. Admin toggle on — an admin must enable Compute large-graph metrics on Databricks in Settings → Global. ONTOBRICKS_ANALYTICS_JOB_ENABLED sets the initial value for a new deployment; once an admin uses the checkbox their choice wins (including an explicit "off").
2. Bundle deployed — the Lakeflow job (resources/graph_analytics.job.yml) must be deployed via make deploy. OntoBricks resolves the job by name (suffix-matching so [dev <user>] prefixes work automatically).
3. Domain built — the domain must have been built at least once after this version of OntoBricks was deployed. Build always produces the R2RML-mapped triples as catalog.schema.triplestore_<domain>_V<n>_data. If that relation is absent or empty, the panel names this requirement and the remedy is a rebuild. Domains built before upgrading to this version need one rebuild.

What the job scores. Analytics reads the mapped triples — the same relation regardless of whether your backend is Lakehouse, Lakebase or Neo4j. Inferred and cohort triples are out of scope; reasoning does not affect the KPIs.

View-only Lakehouse domains. When …_data is a pass-through view rather than a table (see Materialization modes), each run first materializes a temporary …_analytics Delta snapshot and drops it when the run ends. The KPIs are identical; the run just carries the cost of one extra scan of your source tables up front, and needs a configured SQL warehouse to build the snapshot.

Betweenness and closeness are estimates. The job samples ONTOBRICKS_ANALYTICS_JOB_PIVOTS source nodes (default 64) and runs a breadth-first search from each (the Brandes–Pich approach). Both metrics carry an "Estimate" note on the ranking chart. Treat them as a ranking of the clear leaders, not as absolute values. If the BFS hits the depth cap (ONTOBRICKS_ANALYTICS_JOB_MAX_DEPTH, default 32) before the graph is fully explored, betweenness and closeness are withheld entirely — reported as unavailable rather than as numbers — because truncated distance sums would be biased; their distribution tiles then read "Not computed for this run" and the ranking chart explains why. Raise ONTOBRICKS_ANALYTICS_JOB_MAX_DEPTH and re-run to resolve this. Set pivots to 0 to skip both metrics and make the job cheaper; setting pivots at or above the node count makes them exact.

Entity-type counts. The Instances column in the entity-type profile table shows the full population of each class in the mapped graph, including isolated nodes (instances with no relationships). This is a more complete number than earlier releases, which showed only the connected instances on unfiltered runs — types that have isolated nodes will show higher counts.

Running an Analysis

1. Click Run Analysis. An Analysis scope dialog opens, because entity type only takes effect at launch — it is asked for here rather than left in the toolbar, where it could be changed after a run and no longer describe the result on screen.
2. (Optional) Pick an entity type to restrict the analysis to one class (e.g. "Customer"). The scope resets to All types (full graph) every time the dialog opens, so each run is a deliberate choice. Selecting a type shows only instances of that type in the charts while still computing metrics on the full connected subgraph for accuracy. The filter is applied in SQL inside the Lakeflow job, against the Delta snapshot — not by the graph store — so there is no in-memory limit to work around. Cancel closes the dialog without running.
3. Click Run Analysis in the dialog to launch. The analysis starts as a background task (tracked in the global task bell, top-right) and a spinner shows on the page behind while it runs — you can keep working elsewhere in the meantime. When it completes, the stored result loads automatically on the Dashboard tab: six KPI tiles appear (Nodes, Edges, Components, Avg Degree, Density, Elapsed), a distribution strip of five histogram tiles, and one full-width ranking chart for the selected metric. Each new run replaces the previous stored result for that domain version.

Looking for past runs? The Analytics page itself only ever shows the last result per domain version. The full run history — every analysis ever launched, across every version, including failed runs — lives on Knowledge Graph → Management → Runs as a second table below the build-runs table (see Runs (Sidebar) above).

Reading the Dashboard

The Dashboard tab has three layers: KPI tiles, a distribution strip, and a ranking chart.

Distribution strip. Five small histogram tiles — PageRank, Betweenness, Degree, Closeness, Clustering — summarise the score distribution across every scored node in the graph. Each histogram uses 20 linear bins; the median and p90 shown in the tile caption are interpolated approximations from those bin counts (labelled ≈ in the UI). Click a tile to select that metric and redraw the ranking chart; a segmented control in the ranking section header mirrors the selection. The Log scale switch in the section header toolbar is selected by default and redraws all five tiles on a logarithmic count axis — useful for heavy-tailed metrics; turn it off to use raw linear counts. The caption notes when log scale is active because bar heights are no longer proportional to raw counts. If betweenness or closeness could not be computed for this run, that tile reads Not computed for this run instead of a histogram. Results computed before this redesign (legacy cached payloads) still show KPIs, the ranking chart and the detail table; distribution tiles prompt you to re-run the analysis.

Ranking chart. One full-width ranked point-and-line chart shows all scored nodes for the selected metric (default PageRank), ordered by rank from left (highest score) to right (lowest score). The x-axis is rank position and the y-axis is the metric value. Metric switches reuse cached series when available and otherwise issue one request to /dtwin/metrics/series.

The backend always runs one exhaustive ordered metric query. For series up to 5,000 nodes, the response returns every point. Above that threshold, the backend keeps 2,000 representative source points with their original ranks using server-side visual sampling. The chart renders those retained points directly and the status line states both the exhaustive total and the rendered retained-point count.

• Click a point to jump directly to that entity in the Graph Viewer (the filter is pre-populated).
• Hover a point to see rank, label, URI, and score in the tooltip.
• Click the ? button on the ranking chart card header to open an explanation popup with the formula, a worked example, and guidance on why the metric matters.

Below the ranking chart, a PageRank Detail Table lists the top-N entities with all five metrics displayed as mini progress bars, providing full context for why a node ranks highly. Every row is clickable → Graph Viewer.

Data Model Health

After an analysis, a Data Model Health card shows entity types that may not benefit from graph storage:

An entity type is flagged as flat / time-series when:

• It has 0 relationship predicates — all instances are fully isolated (no entity-entity relationships)
• It has exactly 1 relationship predicate across more than 20 instances — suggests a one-dimensional link

Types flagged as flat may not rely on graph semantics. Consider excluding them from the sync or replacing individual rows with aggregated facts in the ontology.

The AI Interpretation agent also mentions flat types in its Key Findings and Recommendations sections.

Adjusting Table Top-N and Resetting

Use the Top N input at the top of the results section to control how many entities the detail table shows. The ranked chart remains exhaustive for the selected metric and is not truncated by this control. To analyse a different class, click Run Analysis again and pick the entity type in the Analysis scope dialog. The funnel line above the results names the scope the displayed result was computed with.

AI Interpretation

After an analysis completes, an Interpret button (✦ icon) appears in the toolbar.

1. Click Interpret — an AI agent (agent_graph_interpreter) calls the LLM serving endpoint configured for the domain. The agent may call get_entity_details one or more times to look up specific top-ranked entities before writing its insights.
2. The AI Insights card renders three structured sections:
   • Key Findings — 2–4 sentences on the graph structure and standout patterns
   • Notable Entities — up to 5 entities with reasons they stand out; clicking an entity name navigates to the Graph Viewer
   • Recommendations — 2–4 actionable suggestions
3. Click Add to audit trail (journal icon in the card header) to save the AI insights as a comment on the current domain version. The discussion panel opens automatically so you can see the new entry.

Tip: The LLM endpoint used is the one set in Domain → Information → LLM Endpoint. If none is configured, interpretation is unavailable and the Interpret button will not appear after analysis.

Discussion Panel

Click the Discussion button (chat-bubble icon, top-right of the Analytics toolbar) to open the comments panel for the current domain version. All review decisions and saved AI insights appear here in chronological order with markdown rendering.

Quality Checks (Sidebar)

Click Data Quality in the sidebar to run automated quality checks on your triple store data:

Running Quality Checks:

1. Ensure your triple store has been synchronized
2. Click Run All Checks button
3. Quality checks run asynchronously — a progress bar shows the current check being executed
4. You can navigate away and return; the task resumes from sessionStorage
5. Results are displayed with pass/fail status once all checks complete

Summary Cards:

• Passed: Number of checks that passed (green)
• Warnings: Number of checks that couldn't be validated (yellow)
• Failed: Number of checks with violations (red)

Check Categories:

1. Cardinality Constraints: Validates min/max/exact cardinality on relationships

   • Example: "Each Employee must have exactly 1 manager"

2. Value Constraints: Validates attribute values

   • contains: Value must contain a substring (e.g., email contains "@")
   • startsWith: Value must start with a prefix
   • endsWith: Value must end with a suffix
   • equals: Value must exactly match
   • matches: Value must match a regex pattern

3. Relationship Properties: Validates property characteristics

   • Functional: Each subject has at most one value
   • Symmetric: If A relates to B, then B relates to A
   • Asymmetric: If A relates to B, then B cannot relate to A
   • Irreflexive: No entity relates to itself

4. Global Rules: Validates global data integrity

   • Require Labels: All entities must have rdfs:label
   • No Orphans: No isolated entities (has relationships)

Viewing Details:

• Click the code icon to view the generated SQL used for the check
• Click the violations count button to see detailed violations in a modal
• The violations modal shows a grid with entity URIs and values that failed the check

Data Quality — SHACL (Sidebar)

Click Data Quality in the Knowledge Graph sidebar to run SHACL shape validations against the triple store:

1. Shapes defined in Ontology → Data Quality are listed with their category, target class, and severity
2. Click Run Validation to execute all enabled shapes
3. Each shape is compiled to SQL and executed against the triple store
4. Results show pass/fail status with violation counts and details
5. For small datasets, PySHACL can validate in-memory without SQL

Inference (Sidebar)

Click Inference in the Knowledge Graph sidebar to run the multi-phase reasoning pipeline:

1. OWL 2 RL — Forward-chaining deductive closure on the ontology (infers subclass hierarchies, domain/range typing, property entailments)
2. SWRL Rules — Evaluates user-defined rules (violation detection and optional materialization)
3. Graph Reasoning — Transitive closure and symmetric expansion based on OWL property characteristics
4. Constraint Checking — Validates cardinality, functional properties, value constraints, and global rules

Results are displayed as inferred triples and violations. Inferred triples can be materialized (written back) to the triple store.

Builders can use Purge Inferences from Build (Lakebase and Lakehouse), Inference, or Cohorts to remove all materialized reasoning and cohort triples from the active graph. The confirmation dialog names the active graph and shows the combined number of generated triples that will be deleted. The Cockpit Knowledge Graph card exposes the same live Materialized inferences count; it includes both reasoning and cohort output. Purging preserves mapped source triples, saved rules, standalone Inference Delta targets, and cohort Unity Catalog output tables. Neo4j reports the count as unavailable and does not offer this operation because it cannot yet distinguish generated triples from source triples safely.

Domain Management & Version Control

OntoBricks stores domains in Unity Catalog Volumes with built-in version control. Navigate to the Domain page by clicking "Domain" in the navigation bar.

Domain Structure

Each domain is stored as a separate Unity Catalog Volume:

• Volume Name: Same as the domain name (sanitized: lowercase, underscores)
• File Names: Version numbers (e.g., v1.json, v2.json, v3.json)
• Contents: Ontology, mappings, design layout, and domain metadata

What is Saved:

• ✅ Ontology (classes, properties, constraints, rules, axioms)
• ✅ Mappings (entity and relationship mappings)
• ✅ Design layout (OntoViz positions and visual configuration)
• ✅ Domain metadata (name, description, author)

What is NOT Saved (Security):

• ❌ Databricks credentials (host, token)
• ❌ Query results
• ❌ R2RML output (regenerated on load)
• ❌ Generated OWL (regenerated on load)

Domain Information (Global Tab)

The Global tab in the Domain Information section contains the main domain settings:

Triple Store Tab

When you commit the domain name (blur the field or trigger change) or change the Version, the Triple Store FQN and Graph DB table name are recomputed so they match the naming rules the server will use on save — without waiting for a round-trip.

Lakehouse objects created by Build (always, in the registry catalog.schema):

Full detail: Architecture → Lakehouse Unity Catalog objects.

Backend details:

Performance:

• Delta materialises the R2RML VIEW into _data with Liquid Clustering (CLUSTER BY (predicate, subject)), co-locating rows by predicate and subject for faster filtering. After each build, an OPTIMIZE runs on _data to compact files and apply the clustering layout. Interactive reads typically hit the _graph union VIEW. Under Views only materialization there is nothing to cluster or optimise, and that read cost moves from a single Delta scan to a full re-execution of the mapping SQL.
• Lakebase stores triples in Postgres flat tables. Two modes are available: app_managed (the app streams batches via COPY FROM STDIN, idempotent on (subject, predicate, object)) and managed_synced (Databricks Lakeflow keeps a synced table in lock-step with the mapped Delta snapshot, while a writable companion table absorbs reasoning/cohort writes — the read view UNIONs both).

Materialization modes (Lakehouse)

A Lakehouse domain chooses how …_data is built, in Domain → Information → Knowledge Graph → Materialization. The rest of the object family is identical either way, and a change takes effect on the next Build.

Two things are unaffected by the choice:

• Inferred triples keep their own …_inferred Delta table. Reasoning and cohort output has no source table to be derived from, so it always lands in real storage.
• Graph Analytics always scans a Delta table. For a view-only domain the job materializes a temporary …_analytics snapshot for the duration of one run and drops it at the end — its iterative BFS would otherwise re-run the whole mapping query on every pass. A leftover snapshot (from a run that died) is listed under Settings → Lakehouse and can be purged there.

Pick Views only when source data changes constantly and you would rather pay per query than rebuild, or when duplicating the triples is not acceptable for governance or cost reasons. Keep the default when the graph is queried interactively — Explorer, GraphQL and reasoning all read through …_graph, and each of those reads inherits the mapping query's cost in view-only mode.

MCP Tab

Controls what an MCP client sees after it selects this domain. The API / MCP toggle on the Global tab decides whether the domain is reachable at all; this tab decides how much of it is published once it is. Nothing here affects the authoring UI, which always shows the full ontology.

A domain that has never been configured keeps the pre-0.8 behaviour: every tool exposed, every attachment surfaced normally.

Exposed Tools — one checkbox per domain-scoped tool (list_entity_types, describe_entity, get_status, get_graphql_schema, query_graphql, get_entity_context, invoke_entity_action), with a Select all master checkbox. Unchecking a tool removes it from the client's tool list for any session on this domain, and refuses the call if a client tries it from a stale, cached list.

The four registry-level tools (list_domains, select_domain, list_domain_versions, get_design_status) are listed read-only underneath. They run before a domain is resolved, so no per-domain policy can govern them — hiding select_domain would make the domain both unusable and unrecoverable.

Ontology Context — the three attachments each take one of three states:

The Actions overlap. The invoke_entity_action tool and the Actions context element are two switches over the same feature. Setting the element to Disabled also refuses invocation, even when the tool stays checked — otherwise a client that already learned a function name could keep running it after the names stopped being advertised. Virtual attributes behaves the same way: disabled, it refuses compute_virtual_attributes(entity_uri) (and the inline compute_virtual_attributes=True flag on get_entity_context) rather than answering with nothing.

Use Preferred to steer an agent that under-uses a genuinely useful attachment, and Disabled to keep a sensitive dataset, a private bridge target, or a side-effecting function out of the model's reach entirely. Disabling is enforced server-side, so it holds for direct REST callers too, not only for the MCP process.

The policy is a domain-level setting, not a per-version one: like the review quorum, it lives on the domain itself and applies to every one of its versions. Editing it while V2 is loaded also changes what V1 publishes, and saving any version persists it. It travels with the domain through exports and imports. See Per-domain MCP policy for the wire format.

Saving Domains

First Save

1. Go to Domain page
2. Fill in domain details:
   • Name: Domain name in CamelCase (becomes the volume folder name)
   • Description: Optional description
   • Author: Your name (auto-filled from Databricks)
3. Select Catalog and Schema for storage
4. Click Save to Unity Catalog

If a domain with the same sanitized folder name already exists in the registry, the save is blocked (inline validation on the domain name and a final check when you confirm save) — pick a different CamelCase name.

OntoBricks will:

1. Create a volume named after your domain (if it doesn't exist)
2. Save the domain as v{version}.json

Subsequent Saves

When you save an existing domain:

• The current version file is overwritten
• Use Create New Version to preserve history

Domain Cockpit (Validation)

Under Domain → Validation (Cockpit), tiles summarise registry and build readiness. The Published Version tile shows which registry version is currently exposed via API and MCP — the numeric-latest version whose lifecycle status is PUBLISHED. That can differ from the version you have loaded in the editor; when it does, the tile adds a (not loaded) hint.

Version lifecycle (DRAFT / IN-REVIEW / PUBLISHED)

Every domain version carries a lifecycle status, shown as a colour-coded badge wherever the domain + version appears (navbar, Domain → Information, Registry → Browse, Domain → Versions, and the query headers):

• DRAFT (amber) — editable. New versions always start here.
• IN-REVIEW (blue) — locked for editing, pending review. Requires a successful build first.
• PUBLISHED (green) — locked for editing and served on the API/MCP.

Transitions are made from Registry → Browse (or Domain → Information): DRAFT → IN-REVIEW → PUBLISHED (admin or builder), IN-REVIEW → DRAFT (admin or builder), and PUBLISHED → DRAFT (admin only). While a version is not DRAFT, its ontology/mapping editors and metadata/document writes stay locked. Builders and admins can still use Build (/dtwin/sync/start), Load (/dtwin/sync/load), and reasoning materialisation to refresh graph data from the frozen design without reverting the version to DRAFT. Read-only Knowledge Graph operations (Explorer filter/expand, stats, status, etc.) also remain fully accessible regardless of lifecycle status.

Single-editor concurrency (open in edit vs. view) & the Close button

To keep two people from silently overwriting each other, a DRAFT version can only be edited by one user at a time:

• The first person to open a DRAFT domain gets it in edit mode.
• Anyone who opens the same domain/version afterwards gets it read-only (view mode), with a banner naming the current editor. All write surfaces are disabled — they can still browse, query and inspect everything.
• The lock is held until the editor explicitly closes the domain, or until their editing session goes idle for the lease period (10 minutes by default). Simply navigating around the app keeps the lease alive automatically, and closing a tab does not hand the domain to someone else straight away — the editor keeps it until they click Close or the lease lapses. The editor's browser quietly renews the lease in the background while the domain is open, so an actively-used session never expires. Hover the domain name in the top navbar while you are editing to see a live countdown of the remaining lease (the time before it would expire if the tab went idle).
• Opening a different domain closes the current one for you. Loading another domain (navbar Load Domain, or Registry → Browse → Load) releases your lock on the previously-open domain before the new one opens, so you never hold two locks at once. Switching to another version of the same domain releases the old version's lock after the new version loads.

Closing a domain — the top sub-navigation shows three buttons: Save (persist the domain to the registry), Switch, and Close. Clicking Close asks whether to save before closing (Save & Close / Close without saving / Cancel), then releases the edit lock and returns you to the Home page. Once you close, the next person can open the domain in edit mode.

Switching version — the Versions button (between Save and Close) opens a popup listing every version of the currently open domain, with the current one flagged. Pick the current version to reload it from the Registry (discarding in-session edits) or another version to switch to it. On a DRAFT version, a "Save my changes before switching" box is ticked by default — leave it on to persist your work first, or untick it to discard unsaved changes. On an IN-REVIEW or PUBLISHED version the version picker stays available but the save option is disabled (those versions are read-only).

Stuck lock? A lock left behind (e.g. a browser that crashed without closing) clears itself: once its lease lapses (no renew for the TTL, 10 minutes by default) the next person to open the version silently reclaims it — no admin action needed. If the original editor comes back after that, they see a "your editing session expired" banner and can Reload to reconnect (regaining edit if no one else has taken over). For an immediate hand-off there are also two manual paths:

• An app-admin viewing the locked version gets a Take over editing button that reclaims the lock; the previous editor becomes read-only on their next page load.
• From Settings → Admin → Locks (admin only), an admin sees every active edit-lock across the registry — domain, version, lifecycle status, who holds it, when it was acquired, and whether its lease has gone stale — and can force-unlock any of them without opening that domain first (a confirmation dialog names the domain, version, and holder).

The lease TTL is configurable from Settings → Global → Edit Lock Lease (minutes) (admin-only; default 10 min). It can also be set via the ONTOBRICKS_EDIT_LOCK_TTL_S environment variable (seconds; default 600) — the Settings value takes precedence over the env var when set. Set either to 0 to disable auto-expiry entirely and require an explicit Close / admin take-over, as in earlier releases.

A version also releases its lock automatically when it leaves DRAFT (submitted for review / published). The read-only banner and the sidebar role badge both name the current holder, so viewers know exactly who to ask to close the domain.

The same user opening the domain in two tabs shares one lock (it is keyed by e-mail), so a reload or a second tab never locks you out of your own domain.

Validation & Review workflow (My Tasks + Domain → Validation)

For a guided, business-user-oriented review on top of the raw lifecycle, OntoBricks adds a review workflow that collects reviewer sign-offs and keeps a durable audit trail.

• Home → My Tasks — a cross-domain worklist of the versions that need you (shown on the home page when you have pending items). Each row shows the domain, version, status, sign-off progress, and the action available to you: Submit for review (builders/admins, on a built DRAFT), Review & sign off (any domain member, on an IN-REVIEW version), or Publish (builders/admins, once the quorum is met). "Review & sign off" loads the domain and opens its Validation workspace.
• Domain → Validation — the per-version review workspace:
  • Consistency checks — a soft readiness summary (ontology valid, mapping complete, warehouse configured, Knowledge Graph built) with shortcuts to the Cockpit and Pitfalls. These checks are advisory and never block publishing.
  • Your actions — context-aware buttons: Submit for review, Approve / Request changes (with an optional comment for the audit trail), Publish, or Reopen.
  • Audit trail — a timeline of every decision (submitted, approved, changes requested, published, reopened) with the actor, timestamp, comment, and the from → to status snapshot for lifecycle transitions.
• Roles & quorum — Submit and Publish stay builder/admin. Publish unlocks for a builder only once the sign-off quorum is reached; an admin (app-level or domain-level) may publish at any time, overriding the quorum (the override is flagged in the audit trail). The quorum is a per-domain setting (default 1), configured on Domain → Information → Global ("Sign-off quorum") and applied to every version of that domain. Sign-off (approve / request changes) is open to any principal with a role on the domain; request changes sends the version back to DRAFT for editing. Reopen (PUBLISHED → DRAFT) is admin-only.
• Persistence — every decision is stored append-only in the domain_review_events registry table, so the full "who validated what, when" history survives restarts and is queryable.

Version Management (Domain → Versions)

1. Open Domain in the sidebar and go to the Versions section.
2. The table lists every saved version with description, author, and actions.
3. MCP / API column: read-only — a green Active badge marks the single version currently exposed through the REST catalogue and MCP tools. To change which version is Active, go to Registry → Browse, expand the domain, and click Set as Active on the desired version (Domain → Versions no longer includes a toggle).
4. Load loads another version from the registry (confirms; unsaved work is lost).
5. New Version copies the current state to the next version number; Reload Saved discards local edits and reloads the current version from the registry.

Creating a New Version

1. Domain → Versions → New Version.
2. OntoBricks increments the version number, saves under /domains/<folder>/V<n>/, and keeps prior versions.

Loading a Domain from Registry

1. Use Load Domain in the top navbar (or Registry → Browse → Load on a version row).
2. Pick domain and version in the dialog. Loading an older than latest version enables read-only mode for edits that require the tip version — create a new version or switch back to the latest to edit freely.

Version status (loaded vs latest vs MCP-active)

Three related ideas:

Domain Save/Load

Domains are saved in a versioned JSON format and can be stored in Unity Catalog Volumes. Use the Save button (in the domain sub-navigation) and the Load Domain option in the top menu to persist and restore your work; the Versions button reloads the current domain or loads another of its versions from the Registry, and the Close button releases the edit lock and returns you to the Home page.

Best Practices for Version Control

1. Version Before Major Changes: Create a new version before significant ontology modifications
2. Use Descriptive Names: Choose domain names that clearly identify the subject area
3. Document Versions: Use the description field to note changes between versions
4. Regular Saves: Save frequently to avoid losing work
5. Test After Loading: Verify R2RML regeneration after loading older versions

Best Practices

Ontology Design

1. Use Meaningful Names: Choose clear, descriptive names
2. Consistent Naming: Use CamelCase for classes, camelCase for properties
3. Start Simple: Begin with core entities, add complexity later
4. Use the Visual Designer: The Design view makes it easy to see relationships
5. Choose Good Icons: Visual icons help identify entities in graphs
6. Set Relationship Directions: Be explicit about data flow direction
7. Use Inheritance Wisely: Create class hierarchies for shared attributes
8. Avoid Deep Hierarchies: Keep inheritance chains shallow (2-3 levels max)

Mapping Strategy

1. Map Core Entities First: Start with main entity types
2. Verify ID Columns: Ensure IDs are unique and stable
3. Test SQL Queries: Always test relationship queries before saving
4. Use Consistent Column Types: Source/target columns should match entity IDs
5. Exclude Irrelevant Attributes Early: Before running Auto-Map, open each entity's Status tab and uncheck attributes you don't need. Auto-Map will skip excluded attributes, producing leaner SQL with no extra columns.
6. Quote Special Column Names: If a source column contains spaces, hyphens, or dots, use backtick quoting in your SQL (`column name` AS column_name) so the mapping and R2RML export work correctly.
7. Use Metadata Quality Warning: Check the Auto-Map page for the metadata quality warning before running Auto-Map — adding table and column descriptions in Domain → Metadata significantly improves mapping accuracy.

Knowledge Graph Tips

1. Sync After Changes: Re-synchronize after modifying ontology or mappings
2. Check Quality: Run quality checks after syncing to catch constraint violations early
3. Use Graph Viewer: The interactive graph is the best way to explore entity relationships
4. Review Triples: Browse the triples grid to verify the generated data looks correct
5. Performance: The /stats API aggregates all scalar metrics in a single SQL query and the /triples/find BFS traversal uses a recursive CTE, minimizing SQL Warehouse round trips
6. Programmatic Access: Use the Knowledge Graph API (/api/v1/digitaltwin/) or the MCP server for programmatic and conversational access to your graph viewer
7. Use Analytics for Governance: Run the Analytics section after each sync to spot high-influence entities (PageRank), bottlenecks (Betweenness), and isolated sub-graphs (connected components count > 1). Use the AI Interpretation feature to get an instant narrative summary of the graph structure.
8. Save Insights to Audit Trail: After interpreting analytics results, click Add to audit trail to keep a record of the AI-generated observations in the domain's review history.

GraphQL API

Once your triple store is materialized (synced via Knowledge Graph), OntoBricks automatically provides a typed GraphQL API for each domain. The schema is auto-generated from the ontology — no manual configuration required.

Accessing GraphQL

1. Navigate to Settings → Developer → API and scroll to the GraphQL API section. The domain selector contains API-exposed PUBLISHED domains only; graph Try-it actions remain disabled for ontology-only or not-yet-built domains while ontology actions stay available.
2. Alternatively, visit /graphql/{domain_name} to open the GraphiQL Playground directly

Available Endpoints

Querying with GraphQL

The auto-generated schema provides two resolvers per ontology class:

• all<ClassName>: List entities with optional limit, offset, and search parameters
• <className>: Fetch a single entity by id

Example query (for an ontology with Customer and Interaction classes):

{
  allCustomer(limit: 10, search: "Smith") {
    id
    label
    email
    hasInteraction {
      label
      date
    }
  }
}

Schema Introspection

Use the SDL endpoint to inspect the full schema:

curl http://localhost:8000/graphql/my_domain/schema

This returns the complete type definitions, which is useful for integrating with external tools or for LLM agents to discover the data model programmatically.

Tips

1. Nested Traversal: Unlike flat triple queries, GraphQL lets you traverse relationships (e.g., customer → interactions → details) in a single query
2. Schema Reflects Ontology: If you add new classes or properties, re-sync the triple store and the GraphQL schema updates automatically
3. GraphiQL Auto-Complete: The playground provides documentation and auto-complete for all types and fields

Relationship Depth Control

GraphQL queries support configurable traversal depth for nested relationships:

• Default depth: 2 (direct neighbors and their neighbors)
• Maximum depth: 5
• How to set: Use the Depth dropdown in the GraphiQL playground, or include "depth": N in the POST request body

Higher depth values allow deeper nested traversal (e.g., customer → interaction → contract → meter) but may increase query time.

MCP Server (Databricks Playground)

OntoBricks includes an MCP server that exposes knowledge-graph tools to LLM clients via the Model Context Protocol. This enables conversational access to your graph viewer from the Databricks Playground, Cursor, Claude Desktop, and other MCP-compatible tools.

Available Tools

The first four are registry-level — they run before a domain is resolved, so they are always available. The other seven are domain-scoped and each domain chooses which of them to publish, from its MCP tab.

Using in Databricks Playground

1. Deploy the MCP server as mcp-ontobricks (see Deployment Guide)
2. In your Databricks workspace, navigate to Playground
3. Select mcp-ontobricks from the MCP Servers list
4. Ask questions like "What entity types are in the graph viewer?" or "Tell me about Jacob Martinez"

Enabling Domains for MCP

Domains must have the API / MCP flag enabled to be visible through the MCP server:

1. Go to Domain > Information > Global tab
2. Toggle Expose via API & MCP to ON
3. Save the domain

Tailoring what a domain publishes

Exposure is all-or-nothing; what happens next is not. Open Domain > Information > MCP to choose which of the seven domain-scoped tools the domain publishes, and whether datasets, bridges and actions are Preferred, Normal or Disabled. The tool list is recomputed when the client calls select_domain, so changes land without restarting the MCP server, and a tool hidden by one domain comes back when the agent hops to another.

See the MCP tab for the full description of each control, and the MCP Server documentation for local usage and client configuration.

Example: HR Domain

Step 1: Design Ontology (Using Visual Designer)

1. Open Ontology → Design
2. Create entities:
   • 👤 Person (add attributes: name, email)
   • 👔 Manager (add attributes: managementLevel)
   • 🏢 Department (add attributes: departmentName)
   • 📋 Project (add attributes: projectTitle, budget)
3. Create inheritance:
   • Click the △ button in the toolbar
   • Drag from Person to Manager → Manager inherits name and email from Person
4. Create relationships:
   • Drag from Person to Department → name it "worksIn" (Forward)
   • Drag from Manager to Project → name it "manages" (Forward)
   • Drag from Person to Person → name it "collaboratesWith" (Bidirectional)
5. Use Auto Layout to organize the diagram
6. Click Center to fit everything in view

Step 2: Create Mappings (Mapping)

1. Open Mapping → Designer
2. Click on each entity to configure its mapping:

Entity Mappings: | Class | Table | ID Column | |-------|-------|-----------| | Person | person | person_id | | Department | department | department_id | | Project | project | project_id |

3. Click on each relationship to configure its mapping:

Relationship Mappings: | Property | SQL Query | Source Col | Target Col | |----------|-----------|------------|------------| | worksIn | SELECT person_id, dept_id FROM person_department | person_id | dept_id | | manages | SELECT manager_id, project_id FROM project_managers | manager_id | project_id | | collaboratesWith | SELECT person1_id, person2_id FROM collaborations | person1_id | person2_id |

Step 3: Explore (Knowledge Graph)

1. Go to Knowledge Graph → Status and click Synchronize to generate triples from your mappings
2. Once synced, click Triples to browse all generated triples in a sortable grid
3. Click Explorer to explore the graph viewer as an interactive sigma.js WebGL graph
4. Click on any entity node to see its type, label, attributes, and values in the details panel
5. Click Data Quality to run automated quality checks against your ontology constraints

Settings Reference

Configuration → UI (Application Branding)

Required role: Administrator. All users see the active branding; only admins can change it.

Navigate to Settings → Configuration → UI to customise how OntoBricks presents itself across every page.

Saved values are instance-wide: they are written to the registry global_config document (ui_branding plus default_emoji) and apply to every user on the next page load. They are not stored in a domain version.

What you can configure

Derived palette

Entering a single primary color automatically generates the full token family: a dark shade, a darker shade, a light/alpha tint, hover and focus ring values, and a WCAG-contrast–safe foreground color (--db-on-primary) guaranteed to meet a ≥ 4.5:1 contrast ratio against the chosen primary. Swatches in the UI preview each derived value before you save.

Semantic status colors (success, warning, danger, info, draft) and all surface, border, and text colors are not affected by this setting — they remain consistent regardless of the primary you choose.

Live preview

Changes to the title, color, or icon take effect immediately in the open Settings page — you can see how the navbar, buttons, focus ring, tab indicators, and other primary-colored elements look before committing. The rest of the app is not yet affected until you save.

Discard removes the local preview and restores the last saved values.

Saving and resetting

• Save writes title, primary color, and logo atomically to the registry (ui_branding). If any field fails validation the save is rejected and nothing is written — the existing branding is preserved.
• Reset icon (the dedicated button in the Branding card) reverts only the icon draft back to the built-in default logo, leaving any unsaved title or color edits intact. The icon is not persisted until you click Save.
• Default restores OntoBricks, #4F46E5, and the built-in logo as a local preview, and immediately restores the factory default entity icon (📦) in the registry. You must still click Save to persist title, color, and logo.
• After a successful save, the new branding is applied to every subsequent page load with no default-color flash: the server injects the CSS variables before any other style loads.

Persistence

The Lakebase registry table is global_config (JSONB). Volume-backed registries store the same object in .global_config.json. A restart of the app does not lose these values.

Icon scope

The configured icon appears as:

• the browser favicon (<link rel="icon">),
• the navbar brand logo (#brandLogoImg),
• the logo shown in the Help modal, KG Chat, and the Ontology Map canvas.

The icon is not resized or cropped server-side; use a square asset for best results across all sizes.

Troubleshooting

Connection Issues

Problem: "Connection failed" error

Solutions:

• Verify Databricks host URL is correct (include https://)
• Check token has not expired
• Ensure SQL Warehouse is running
• Verify network connectivity

No Tables Showing

Problem: Empty table list in mapping modal

Solutions:

• Verify catalog and schema names are correct
• Check permissions on the schema
• Ensure tables exist in the schema

Query Test Fails

Problem: SQL query test returns error

Solutions:

• Check SQL syntax
• Verify table and column names
• Ensure you have SELECT permissions
• Only SELECT queries are allowed

Empty Graph Viewer

Problem: Graph shows no nodes or edges

Solutions:

• Ensure the triple store has been synchronized (check Triples section)
• Verify relationships exist in data
• Click "Fit to View" button
• Click the reload button to re-render the graph
• Check browser console for errors

Mapping Validation Fails

Problem: Error when validating mappings

Solutions:

• Ensure all ontology classes are mapped (via Mapping → Designer)
• Check all object properties have relationship mappings
• Verify all entity attributes are assigned to SQL columns (check for orange indicators in Designer view)
• Use Auto-Map → Re-Assign Missing Attributes to fix incomplete attribute mappings
• Verify table and column names match

Lakebase Graph Empty After Restart

Problem: Triples are missing from the Graph DB after the App restarts

Solutions:

• Lakebase Postgres is the source of truth for the graph engine — verify the App is bound to the Lakebase instance (PGHOST / PGDATABASE env vars set by the Apps runtime)
• If the Lakebase instance was paused or scaled to zero, the connection layer retries on SQLSTATE 57P03. Wait a few seconds and re-trigger the build.
• Re-run the Knowledge Graph sync — the build is idempotent (INSERT … ON CONFLICT DO NOTHING)
• For managed_synced mode, check the Lakeflow synced-table status under Settings → Back end

Design Changes Not Saving

Problem: Changes in Design view are not persisted

Solutions:

• Wait for the "Saving..." indicator to complete
• Check browser console for errors
• Ensure you have network connectivity
• Try refreshing the page

Relationship Direction Issues

Problem: Direction not displaying correctly

Solutions:

• Click the direction button (→/←/↔︎) to cycle through options
• Verify the direction is set in both Design and Relationships views
• Check that source and target entities are correctly identified

Keyboard Shortcuts

Navigation

• Deep-linked sections: Sidebar section changes update the URL (?section=<id>), so you can bookmark or share a specific section. Browser Back/Forward navigates between previously visited sections.
• Breadcrumb bar: A breadcrumb trail below the navbar shows your current position (e.g. Registry > Domain > Ontology > Entities) and updates as you switch sidebar sections.

Support

• Review the Architecture documentation
• Check the API Reference
• See Deployment Guide for production setup
• Check sample data in the data/ folder

Automated triple-store pipeline (merged)

Automated Triple Store Creation

This guide walks you through creating a fully populated graph viewer triple store from scratch using OntoBricks' automated features. With LLM-powered ontology generation, automatic data mapping, and one-click synchronization, you can go from raw Databricks tables to a queryable triple store in minutes.

Prerequisites

Before you start, make sure you have:

• A Databricks workspace with tables in Unity Catalog
• A SQL Warehouse (Serverless or Classic)
• A Databricks Model Serving endpoint (for LLM features — e.g., databricks-meta-llama-3-3-70b-instruct, or any chat/completions endpoint)
• A Personal Access Token with permissions to read tables and execute queries

Overview

The automated pipeline follows these steps:

Step 1: Configure connection
        │
Step 2: Set up domain (LLM endpoint, triple store table)
        │
Step 3: Import table metadata from Unity Catalog
        │
Step 4: Generate ontology with the Wizard (LLM-powered)
        │
Step 5: Auto-Map data mappings (LLM-powered)
        │
Step 6: Synchronize to the triple store
        │
Step 7: Validate with quality checks
        │
        ▼
   Knowledge graph ready

Step 1: Configure Databricks Connection

Navigate to Settings (gear icon in the top-right corner).

1. Enter your Databricks Host URL (e.g., https://your-workspace.cloud.databricks.com).
2. Enter your Personal Access Token.
3. Click Test Connection to verify connectivity.
4. Select a SQL Warehouse from the dropdown list.
5. Click Save.

The connection status indicator in the navbar should turn green.

Step 2: Set Up the Domain

Navigate to Domain in the top navbar, then open the Information sidebar section.

1. Enter a Domain Name (e.g., CustomerAnalytics).
2. Set the Base URI for your ontology (e.g., https://ontobricks.com/ontology/). This is the namespace for all generated RDF resources.
3. Select the LLM Endpoint from the dropdown. This is the Databricks Model Serving endpoint used for ontology generation and auto-mapping.
4. Configure the Triple Store Table: select a catalog, schema, and table name where triples will be stored (e.g., my_catalog.my_schema.triples). The table will be created automatically during sync.

Step 3: Import Table Metadata

Navigate to Domain > Metadata in the sidebar.

This step tells OntoBricks about the Databricks tables you want to model in your ontology.

1. Select a Catalog from the dropdown.
2. Select a Schema from the dropdown.
3. Click List Tables to see all available tables.
4. Check the tables you want to include in your ontology (or use "Select All").
5. Click Initialize Metadata.

OntoBricks fetches column names, types, and comments from Unity Catalog for each selected table. This metadata is used by the Wizard and Auto-Map features to understand your data structure.

Tip: Include all tables that are relevant to the domain you want to model. The more context the LLM has, the better the ontology and mappings will be.

Refreshing metadata (Update from UC)

Update from UC re-reads the schema of the selected tables (or all of them when nothing is checked). Because the merge replaces the stored column list outright and cannot be undone, the changes are shown for review before they are applied:

• A Review Metadata Changes dialog lists, per table, the columns that were added, removed, or had their data type change, along with a count of the unchanged ones.
• Apply Changes writes the refresh to the domain; Discard throws it away and leaves the stored metadata exactly as it was.
• When Unity Catalog reports no column changes the refresh is applied silently — the dialog only appears when there is something to decide.
• If any column was dropped, the dialog warns that mappings bound to it will break, so run Mapping → Diagnostics afterwards.

Your own column comments survive a refresh: a comment you typed in OntoBricks is carried over whenever the column still exists upstream.

Removing data sources

Removing a table (Remove Tables, or Clear Data Sources for all of them) is checked against the mappings first. If any entity or relationship still reads from a table you are about to remove, a Data Sources Still In Use dialog lists each affected table together with the mappings that reference it — for example Entity: Customer or Rel: buys (source). References buried inside a mapping's custom SQL are detected too.

You can still confirm the removal: the guard informs rather than blocks, matching Unmap all and Clear metadata. When you proceed, the generated R2RML and SQL are cleared, because they would otherwise describe a table the domain no longer knows about.

Step 4: Generate the Ontology with the Wizard

Navigate to Ontology in the top navbar, then open Generate in the sidebar.

The Wizard uses your LLM endpoint and the imported metadata to automatically design an ontology.

1. You'll see the list of tables loaded from metadata. Check the tables you want the LLM to consider.
2. (Optional) Click a Quick Template button to pre-fill domain-specific guidelines:
   • CRM — customers, contacts, accounts, opportunities
   • E-Commerce — products, categories, orders, payments
   • IoT — devices, sensors, measurements, locations
   • Healthcare — patients, providers, appointments, diagnoses
   • Energy — energy-sector customer relationship management
3. Review or edit the guidelines text area. You can add specific instructions like "Create a Customer entity with relationships to Contract and Invoice."
4. Configure generation options:
   • Include Data Properties — generate attributes for entities
   • Include Relationships — generate relationships between entities
   • Include Inheritance — generate class hierarchies
   • Use Table Names — use original table names as entity names
   • Use Column Comments — use UC column comments in descriptions
5. Click Generate.
6. The LLM generates an OWL ontology in Turtle format. You can preview the result.
7. Click Apply to import the generated ontology into your domain.

After applying, switch to the Model view in the sidebar to see the visual ontology with entities, relationships, and inheritance links.

Tip: You can edit the generated ontology afterwards — add or remove entities, rename relationships, set icons, adjust attributes.

Step 5: Auto-Map Data Mappings

Navigate to Mapping in the top navbar, then open Auto-Map in the sidebar.

Auto-Map uses the LLM to automatically generate SQL queries that map each ontology entity and relationship to your Databricks tables.

1. Review the list of unmapped entities and unmapped relationships.
2. Click Start Auto-Map.
3. OntoBricks processes each entity and relationship:
   • Sends the entity name, attributes, and metadata context to the LLM
   • The LLM generates a SQL query (SELECT statement)
   • The SQL is validated by executing it against the SQL warehouse
   • Column mappings are inferred (ID, Label, and attribute columns)
4. A progress bar shows the mapping progress.
5. When complete, review the results — successfully mapped items show in green.
6. Click Apply All to save all mappings to the domain.

You can verify individual mappings by switching to the Designer view:

• Green nodes = fully assigned (all attributes mapped)
• Orange nodes = partially assigned (some attributes missing)
• Red nodes = unassigned

Tip: If some entities remain unassigned or partially assigned, you can click on them in the Designer view to manually edit or regenerate their SQL mapping.

Step 6: Synchronize to the Triple Store

Navigate to Knowledge Graph in the top navbar. The Status section opens by default.

Before syncing, OntoBricks validates readiness:

• Ontology: At least one entity with a valid URI
• Entity Mappings: All entities have SQL assignments
• Relationship Mappings: All relationships have SQL assignments

If all checks pass:

1. Click Synchronize.
2. OntoBricks:
   • Generates R2RML mappings from your entity and relationship assignments
   • Translates the mappings into Spark SQL queries
   • Executes the queries against your SQL warehouse
   • Creates the triple store table (Delta format) with columns: subject, predicate, object
   • Inserts all generated triples
3. A progress indicator shows the sync status.
4. When complete, you'll see the triple count and last updated timestamp.

Note: If the triple store table already exists, you can choose to drop and recreate it or append to the existing data.

Triple Store Backend: OntoBricks always materializes a Delta view in Unity Catalog (governance + lineage) and a flat triple table in the domain's Graph DB engine (Lakebase Postgres, Lakehouse, or Neo4j). The backend is chosen per domain under Domain → Information → Knowledge Graph (engine connection settings live under Settings → Back end).

Step 7: Validate with Quality Checks

Still in the Knowledge Graph section, open Data Quality in the sidebar.

Quality checks validate the triple store against your ontology using two complementary systems:

Legacy Constraint Checks

These check OWL property constraints defined in the ontology:

SHACL Data Quality Shapes

Define fine-grained rules using the W3C SHACL standard (Ontology > Data Quality sidebar):

SHACL shapes are compiled to Spark SQL and executed on the SQL warehouse against the triple-store VIEW, whatever graph engine the domain uses. Results show violations, pass rates, and per-entity details.

1. Click Run All Checks to execute all applicable checks, or run individual checks.

2. Results show pass/fail for each check with details on any violations.

3. Use the results to identify data quality issues in your source tables or ontology design.

Step 7b: Run Reasoning (Optional)

Still in the Knowledge Graph section, open Inference in the sidebar.

Reasoning discovers new facts (inferred triples) from your ontology rules:

1. Select the reasoning phases to run:
   • T-Box (OWL 2 RL): Infers class hierarchies, property inheritance, and domain/range constraints
   • SWRL Rules: Executes your custom business rules (e.g., "if Person hasParent Parent and Parent hasParent Grandparent, then Person hasGrandparent Grandparent")
   • Structural: Applies transitivity, symmetry, and other property characteristics
2. Optionally enable Materialization to write inferred triples back to the triple store
3. Click Start Reasoning
4. Review the inferred triples — each shows the source rule and reasoning phase

Note: Reasoning is most effective when you have SWRL rules defined (Ontology > Business Rules) and a rich ontology with property characteristics.

Step 8: Explore Your Graph Viewer

After sync, you can explore the triple store:

Graph Explorer

Open Explorer in the sidebar to explore the graph viewer interactively:

• Find specific entities by name, type, or URI — matching entities and their neighbors are highlighted
• Filter by entity type, field, match type, and relationship depth
• Navigate relationships — click an entity to see its attributes, values, and connected entities in the detail panel
• Toggle labels for node and edge labels
• Hide orphans to focus on connected entities

Complete Workflow Summary

After the initial one-time configuration (steps 1–2), the entire pipeline from metadata to triple store is four clicks: Import Metadata, Generate, Auto-Map, Synchronize.

Tips for Best Results

• Table and column naming: The LLM performs best when table and column names are descriptive. If your tables use cryptic names, add comments in Unity Catalog before importing metadata.
• Start with a template: Use one of the Wizard quick-templates (CRM, IoT, etc.) if your domain matches — it provides better guidelines for the LLM.
• Review before syncing: After auto-map, quickly review the Designer view. Fix any red or orange nodes before synchronizing.
• Iterate: The pipeline is not a one-shot process. You can re-generate the ontology, re-run auto-map, or manually adjust individual mappings at any time.
• Save your domain: After achieving a good result, save the domain to Unity Catalog (Save in the domain sub-navigation) so you can reload it later.

REST API — Programmatic Pipeline

The full pipeline is also available via REST API for automation or CI/CD integration:

## Step 3: Import metadata
curl -X POST /domain/metadata/initialize-async \
  -d '{"catalog": "my_catalog", "schema": "my_schema", "tables": ["t1", "t2"]}'

## Step 4: Generate ontology
curl -X POST /ontology/wizard/generate-async \
  -d '{"metadata": {...}, "guidelines": "...", "options": {...}}'

## Step 4b: Apply generated ontology
curl -X POST /ontology/import-owl \
  -d '{"content": "<turtle content>"}'

## Step 5: Auto-Map
curl -X POST /mapping/auto-assign/start \
  -d '{"entities": [...], "relationships": [...], "schema_context": {...}}'

## Step 6: Sync
curl -X POST /dtwin/sync/start \
  -d '{"triplestore_table": "catalog.schema.table", "drop_existing": true}'

## Step 7: Quality checks
curl -X POST /dtwin/quality/start \
  -d '{"triplestore_table": "catalog.schema.table"}'

Async endpoints return a task_id. Poll GET /tasks/{task_id}/status for progress and results.

Programmatic & MCP Access

After your graph viewer is built, it can be queried programmatically:

• Knowledge Graph API (/api/v1/digitaltwin/): Stateless REST endpoints for triple store status, entity search, ontology retrieval, and more. See External API.
• GraphQL API (/graphql/{domain_name}): Auto-generated typed schema with nested relationship traversal. See External API.
• MCP Server: Expose your graph viewer to the Databricks Playground and LLM clients. See MCP Server.

Ontology import (merged)

Importing Ontologies

OntoBricks supports multiple ways to create or bootstrap an ontology: from scratch using the visual designer, from OWL/RDFS files, or by importing industry-standard ontologies. This page covers every import method available in the Ontology > Import section.

Import Methods at a Glance

All imports merge the fetched content, parse it, and store the result in the current domain session. You can continue editing entities, relationships, and attributes after import.

OWL Import

Import an ontology written in the Web Ontology Language (OWL).

From a Local File

1. Open Ontology > Import > OWL.
2. Click Choose File and select an OWL file (.ttl, .owl, .rdf, .xml).
3. Click Import.
4. OntoBricks parses the file and loads all classes, properties, constraints, SWRL rules, and axioms.

From Unity Catalog

1. In the same OWL tab, switch to the Unity Catalog sub-tab.
2. Select a Catalog, Schema, and Volume from the dropdown lists.
3. OntoBricks lists the OWL files found in the volume.
4. Select a file and click Load.

RDFS Import

Import an RDF Schema file. RDFS provides a lighter vocabulary than OWL — class hierarchies and property definitions are supported.

1. Open Ontology > Import > RDFS.
2. Choose a local file or a Unity Catalog Volume file (.ttl, .rdf, .xml, .rdfs, .n3, .nt).
3. Click Import.

FIBO — Financial Industry Business Ontology

FIBO is developed by the EDM Council and provides a comprehensive ontology for the financial industry: entities, instruments, products, business processes, and regulatory concepts.

Available Domains

How to Import

1. Open Ontology > Import > FIBO.
2. Check the domains you want. Foundations (FND) is always included because all other domains depend on it.
3. Click Import Selected Domains.
4. OntoBricks fetches the modules from spec.edmcouncil.org, merges them with RDFLib, and parses the result.
5. A summary notification shows the number of classes and properties imported.

Source

Modules are downloaded from the EDM Council specification server:

https://spec.edmcouncil.org/fibo/ontology/master/latest/

CDISC — Clinical Data Interchange Standards

CDISC standards define data models for clinical research. OntoBricks imports the RDF representations published by the PhUSE working group.

Available Standards

How to Import

1. Open Ontology > Import > CDISC.
2. Check the standards you want. Schemas is always included.
3. Click Import Selected Standards.
4. OntoBricks fetches the modules from GitHub, merges them, and applies a custom mapper that translates CDISC-specific constructs (DomainContext, Domain, Dataset, DataElement) into OWL classes and properties.

Source

Modules are downloaded from the PhUSE GitHub repository:

https://github.com/phuse-org/rdf.cdisc.org

Note on CDISC Mapping

When CDISC standard data (SDTM, CDASH, etc.) is imported, OntoBricks uses a specialized mapper rather than the generic OWL parser:

• DomainContext entries become top-level OWL classes.
• Domain / Dataset entries become OWL classes grouped under their context.
• DataElement entries become data properties attached to their parent domain.

This produces a more meaningful ontology structure than a raw RDF parse.

IOF — Industrial Ontologies Foundry

IOF is developed by OAGi and provides ontologies for digital manufacturing. All IOF ontologies are built on BFO (Basic Formal Ontology).

Available Domains

How to Import

1. Open Ontology > Import > IOF.
2. Check the domains you want. Core is always included because all domain ontologies depend on it.
3. Click Import Selected Domains.
4. OntoBricks fetches the RDF modules from GitHub, merges them with RDFLib, and parses the result.
5. A post-processing step extracts relationships from OWL restrictions and resolves BFO property labels to human-readable names.

Source

Modules are downloaded from the IOF GitHub repository:

https://github.com/iofoundry/ontology

Note on BFO-Based Ontologies

IOF ontologies define most class-to-class relationships through OWL restrictions (owl:someValuesFrom / owl:allValuesFrom inside rdfs:subClassOf) rather than explicit rdfs:domain / rdfs:range on properties. OntoBricks includes a dedicated extraction step that:

1. Scans rdfs:subClassOf and owl:equivalentClass axioms for restriction patterns.
2. Resolves opaque BFO property URIs (e.g., BFO_0000057) to readable labels (e.g., hasParticipantAtSomeTime) using graph labels and a built-in dictionary.
3. Filters out relationships whose endpoints reference external BFO classes not present in the import.

This ensures the ontology model displays accurate, readable relationships.

REST API Endpoints

All import operations are also available through the REST API.

See the API Reference for complete request/response details.

Common Import Workflow

Regardless of the method, the import workflow follows the same pattern:

Select source & options
        │
        ▼
Fetch modules (concurrently for standards)
        │
        ▼
Merge into a single RDFLib graph
        │
        ▼
Serialize to Turtle
        │
        ▼
Parse with OWL/RDFS parser
        │
        ▼
Post-processing (filtering, restriction extraction, label resolution)
        │
        ▼
Store in domain session
        │
        ▼
UI refreshes (entities, relationships, map)

After import you can:

• Edit entities, relationships, and attributes in the visual designer or form views.
• Add new entities or relationships on top of the imported ontology.
• Map entities to Databricks tables in the Mapping section.
• Export the combined ontology as OWL/Turtle.

Tips

• Start small: When importing a large standard like FIBO, start with the required foundation module and one domain to evaluate the result before adding more.
• Network access: Industry-standard imports require outbound internet access to fetch modules from their public repositories. If running in Databricks Apps with restricted egress, download the files manually and use the OWL file import instead.
• Incremental import: Each import replaces the current ontology. If you need to combine multiple standards, export after each import and merge the OWL files externally.
• Layout reset: After importing a large ontology, use Auto-Layout in the Ontology Designer view to arrange entities automatically.