Skip to content

user-guide.md

Latest commit

 

History

History
1831 lines (1317 loc) · 95.8 KB

user-guide.md

File metadata and controls

1831 lines (1317 loc) · 95.8 KB
Raw

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

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:

Type Subject Objects
Equivalent Classes Employee Person, hasJob
Disjoint With Person Organization
Union Of Contact Person, Company
Inverse Of isParentOf hasParent
Property Chain hasGrandparent hasParent, hasParent

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:
Category Purpose Example Constraints
Completeness Required fields exist sh:minCount 1 — every entity must have a label
Cardinality Correct number of values sh:maxCount 3 — at most 3 phone numbers
Uniqueness Values are unique sh:hasValue — specific value required
Consistency Type-correct references sh:class — target must be of correct type
Conformance Format compliance sh:pattern — email must match regex; sh:minInclusive / sh:maxInclusive — monthly fee between 1 and 10; sh:minLength / sh:maxLength — code is 3 to 8 characters
Structural Graph structure rules sh:closed — no unexpected properties
  1. Select the Target Class and Property to constrain
  2. Choose the SHACL Constraint Type (minCount, maxCount, pattern, datatype, class, hasValue, etc.)
  3. Configure constraint-specific parameters
  4. Optionally add conditions (conformance and consistency rules only) — see below
  5. Set Severity (Violation, Warning, Info) and an optional Message
  6. 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.

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.

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, clicking directly loads the Mapping tab and runs the query automatically (direct edit mode)
  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.

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.

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.

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)

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 and Bridges 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 unconditionally materialises a Delta snapshot of the R2RML-mapped triples (catalog.schema.triplestore_<domain>_V<n>_data). If that snapshot 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-triple snapshot — the same table regardless of whether your backend is Lakehouse, Lakebase or Neo4j. Inferred and cohort triples are out of scope; reasoning does not affect the KPIs.

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, not just the top-N shown in the ranking chart. That is the key distinction: the strip answers "is this node's score unusual for the graph as a whole?", while the ranking chart below lists only the top-N leaders for the metric you have selected. 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. Use the Log scale switch in the section header toolbar — between the Top N input and the Run Analysis button — to redraw all five tiles on a logarithmic count axis — useful for heavy-tailed metrics; 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.

Metric What it measures
PageRank Global influence — nodes that are pointed to by other influential nodes rank highest
Betweenness Centrality Bridging role — nodes that lie on many shortest paths between other nodes
Degree Centrality Raw connectivity — fraction of other nodes this node is directly connected to
Closeness Centrality Reachability — how quickly this node can reach every other node in the graph
Clustering Coefficient Local density — fraction of a node's neighbors that are also connected to each other

Ranking chart. One full-width horizontal bar chart shows the top-N entities for whichever metric is selected (default PageRank). The ranking chart covers only the bounded top-N slice — unlike the distribution strip above, which spans the whole scored population.

  • Click a bar to jump directly to that entity in the Graph Viewer (the filter is pre-populated).
  • Hover a bar to see all five metric scores for that entity 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:

Column Meaning
Entity Type Class URI local name
Instances Count of instances in the graph
Rel. Predicates Distinct entity-to-entity relationship predicates (excludes rdf:type, rdfs:label, and literal attributes; counts both incoming and outgoing relationships)
Temporal Whether any camelCase/snake_case token of a predicate name is a temporal keyword (e.g. date, timestamp, at)

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 the Top-N and Resetting

Use the Top N input at the top of the results section to control how many entities the ranking chart and detail table show. 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.

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:

Field Description
Domain Name CamelCase, alphanumeric only (e.g. MyOntologyDomain). Defaults to NewDomain. Non-alphanumeric characters are stripped automatically and words are capitalized as you type.
Version Current version number with version selector.
Base URI The base namespace for all ontology entities. By default, auto-generated from Settings → Default Base URI Domain / DomainName#. Toggle the Custom switch to enter a custom URI.
Description Free-text description of the domain.
Author Automatically pre-filled with the current Databricks user email. Editable.
API / MCP Toggle Expose via API & MCP to make this domain visible through the REST API (/api/v1/domains) and the MCP server. Disabled by default.

Triple Store Tab

Field Description
Backend Select the Graph DB engine for this domain (lakebase, databricks / Lakehouse, or neo4j). Build always also creates the Unity Catalog triple-store family below.
Triple-Store Read-only. Base name in the domain's registry catalog.schema: triplestore_<domain>_V<version>. Build creates four related objects from that base (see below).
Graph DB table Read-only. For Lakebase, the flat triple table name is derived as g_<domain>_v<version> in the configured Postgres schema (default ontobricks_graph).

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):

Object Kind What it is for
triplestore_<domain>_V<n> VIEW Live R2RML mapping over your source tables
…_data Delta TABLE Materialised mapped triples — what Analytics reads; also the bulk half of the graph
…_inferred Delta TABLE Reasoning / cohort / app-written triples
…_graph VIEW _data ∪ _inferred — what Explorer and most graph reads use

Full detail: Architecture → Lakehouse Unity Catalog objects.

Backend details:

Backend Storage Sync Best for
Lakehouse (Delta) The UC objects above (SQL Warehouse) Build CTAS + companion tables Unity Catalog governance, analytics on the mapped snapshot, no separate graph DB
Lakebase Postgres Flat (subject, predicate, object) table on the App-bound Lakebase instance App-managed (COPY FROM STDIN) or managed-synced (Lakeflow) Low-latency reads from the FastAPI process, reasoning, BFS / cohort builds
Neo4j Bolt-connected property graph Build MERGE of mapped triples Cypher traversal workloads

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.
  • 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).

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, the ontology/mapping editors, metadata/document writes, and the Build (/dtwin/sync/start) and Load (/dtwin/sync/load) actions are blocked server-side — set it back to DRAFT to rebuild. Read-only Knowledge Graph operations (Explorer filter/expand, stats, status, etc.) 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:

Concept Meaning
Loaded version The v{n} document currently in your browser session.
Latest on disk Highest version number in the registry folder. When your loaded version is not the latest, the UI treats many writes as read-only.
Active (API/MCP) The one version flagged for external tools and MCP — shown on the Cockpit Active Version tile and as a badge on Domain → Versions; changed only from Registry → Browse.

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 Knowledge Graph → API and scroll to the GraphQL API section
  2. Alternatively, visit /graphql/{domain_name} to open the GraphiQL Playground directly

Available Endpoints

Endpoint Method Description
/graphql GET List all GraphQL-enabled domains
/graphql/{domain_name} GET Open GraphiQL playground for a domain
/graphql/{domain_name} POST Execute a GraphQL query
/graphql/{domain_name}/schema GET Get the SDL (Schema Definition Language)

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

Tool Description
list_domains List all domains with ≥1 PUBLISHED version in the registry
select_domain Activate a domain for subsequent queries
list_domain_versions List registry versions for a domain
get_design_status Ontology / metadata / assignment readiness for a domain
list_entity_types Overview of entity types, counts, and predicates
describe_entity Full-text description of an entity with BFS traversal
get_entity_context Linked dataset rows, cross-domain bridges, and class actions for a node
invoke_entity_action Run a Unity Catalog function action on an entity (entity ID passed as the single argument)
get_graphql_schema Auto-generated GraphQL schema (SDL) for the domain
query_graphql Execute a GraphQL query with structured results
get_status Triple store diagnostic (view, graph, count)

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

See the MCP Server documentation for full details including 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
  1. 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

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

Shortcut Action
Ctrl/Cmd + S Save domain
Ctrl/Cmd + K Focus sidebar search (if available)
? Show / hide the keyboard shortcuts overlay
Ctrl/Cmd + Enter Confirm action
Tab Navigate between form fields
Enter Submit form / confirm dialog
Escape Close modal or shortcut overlay

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

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.

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:

Check What It Validates
Cardinality Min/max/exact property counts per entity
Functional At most one value per subject for a property
Inverse Functional At most one subject per object for a property
Symmetric If A→B exists, B→A must also exist
Asymmetric No symmetric pairs allowed
Irreflexive No self-referencing triples
Require Labels All entities have rdfs:label
No Orphans No entities with only type and label

SHACL Data Quality Shapes

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

Shape Type What It Validates
sh:minCount / sh:maxCount Required fields, exact cardinality
sh:datatype Value type (integer, date, boolean, string)
sh:pattern Regex pattern matching
sh:hasValue Required specific values
sh:class Object must be of a specific type
sh:sparql Custom SPARQL-based rules (e.g., no orphans, unique IDs)

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

Step Where Action Automated?
1 Settings Configure Databricks connection Manual (one-time)
2 Domain > Information Set LLM endpoint and triple store table Manual (one-time)
3 Domain > Metadata Import table metadata from Unity Catalog One click
4 Ontology > Generate Generate ontology from metadata using LLM One click
5 Mapping > Auto-Map Auto-map entities and relationships to SQL One click
6 Knowledge Graph > Build Synchronize to triple store One click
7 Knowledge Graph > Data Quality Run quality checks One click

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

Method Source Formats Use Case
OWL Local file or Unity Catalog Volume .ttl, .owl, .rdf, .xml Load an existing OWL ontology
RDFS Local file or Unity Catalog Volume .ttl, .rdf, .xml, .rdfs, .n3, .nt Load an RDF Schema
FIBO EDM Council spec server RDF/XML, Turtle Financial industry ontology
CDISC PhUSE GitHub repository RDF/XML, Turtle Clinical data standards
IOF IOF GitHub repository RDF/XML Digital manufacturing ontology

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

Domain Key Required Description
Foundations FND Yes (auto-included) Core concepts: parties, agreements, relations, dates, organizations, accounting
Business Entities BE No Legal entities, corporations, partnerships, government bodies, ownership structures
Financial Business & Commerce FBC No Financial products, services, intermediaries, markets, instruments
Loans LOAN No Loan products, applications, mortgages, real estate lending
Securities SEC No Equities, bonds, debt instruments, investment funds
Derivatives DER No Options, futures, swaps, commodity and currency contracts

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

Standard Key Required Description
Schemas SCHEMAS Yes (auto-included) Meta-Model (ISO 11179), CT Schema, CDISC Schema — the foundational layer
SDTM SDTM No Study Data Tabulation Model (v1.2, v1.3, IG 3.1.2, IG 3.1.3)
CDASH CDASH No Clinical Data Acquisition Standards Harmonization (v1.1)
SEND SEND No Standard for Exchange of Nonclinical Data (IG 3.0)
ADaM ADaM No Analysis Data Model (v2.1, IG 1.0)

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

Domain Key Required Description
Core CORE Yes (auto-included) Common manufacturing concepts: agents, processes, capabilities, organizations, products, business functions
Maintenance MAINTENANCE No Maintenance management, procedures, asset failure analysis, FMEA
Supply Chain SUPPLYCHAIN No Procurement, transportation, warehousing, distribution, logistics

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.

Method Endpoint Description
POST /ontology/parse-owl Parse OWL content (body: {"content": "..."})
POST /ontology/parse-rdfs Parse RDFS content (body: {"content": "..."})
GET /ontology/list-owl-files List OWL files in a UC Volume (params: catalog, schema, volume)
POST /ontology/load-owl-file Load an OWL file from UC (body: catalog, schema, volume, filename)
GET /ontology/{kind}-catalog Get an industry ontology catalog (kind = fibo, cdisc, or iof)
POST /ontology/import-{kind} Import an industry ontology (kind = fibo, cdisc, or iof; body: {"domains": [...]})

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.