Build your first knowledge graph

Before you begin

This guide assumes OntoBricks is already running and connected to your workspace. If not, follow the Install step by step guide first — it takes about 20 minutes.

The 4-click pipeline

Most of what follows is automated. At its core, OntoBricks turns metadata into a queryable graph in four moves — LLM-powered automation does the heavy lifting while you stay in control:

1 Create a domain

A domain is one self-contained ontology + graph, versioned in the registry. Everything you build lives inside it.

1. From Home or Registry, click New Domain. A full-page loading overlay runs until Domain Information finishes its first load.
2. Open Domain → Information and set the domain name (e.g. customer360). Commit it by blurring the field — the triple-store and snapshot paths update from the name.
3. Your new version starts in DRAFT status (shown as a colour-coded badge in the navbar). Only DRAFT versions are editable.

2 Import Unity Catalog metadata

Give OntoBricks the schema it will model. This is click 1 of the automated pipeline.

1. Go to Domain → Metadata.
2. Pick the catalog and schema, then select the tables you want in your graph.
3. OntoBricks fetches the table and column metadata from Unity Catalog so it understands what it's modelling — no data is moved yet.

3 Design the ontology

You have three ways to get an ontology — pick whichever suits you.

Fastest — generate with AI (click 2)

1. Open Ontology → Generate.
2. An LLM designs entities, relationships, and attributes directly from your imported metadata — a fully editable starting point.
3. Optionally start from a quick template (CRM, E-Commerce, IoT, Healthcare, Energy).

Visual — the Designer canvas

Open Ontology → Designer (the OntoViz canvas) to draw entities and relationships by hand:

• Add an entity, click its name to rename it (e.g. Person), then use + to add attributes, 🎨 for an icon, 📝 for a description.
• Drag from one entity's connector (○) to another to create a relationship; rename it (e.g. worksIn) and set its direction (→ / ← / ↔).
• Use Auto Layout and Center to tidy the diagram; scroll to zoom. Changes save automatically.

A floating AI Assistant (bottom-right of the canvas) lets you edit the ontology in natural language — "add a Department entity", "remove orphans", "list relationships".

Import a standard

From Ontology → Import you can bring in OWL/RDFS or industry standards — FIBO, CDISC, IOF, HL7 FHIR — as a starting point.

When you're happy, click OWL to preview the generated Turtle, Validate to check it, and Save to store it in Unity Catalog. The navbar Ontology indicator turns green ✓.

4 Map entities to tables

Mapping binds each ontology entity to the rows and columns that populate it. This is click 3.

Fastest — Auto-Map

Go to Mapping → Auto-Map. An LLM writes the R2RML mappings for every entity and relationship, with multi-pass column matching and partial-mapping detection.

Precise — the visual Designer

1. Open Mapping → Designer and click an entity to open its mapping dialog.
2. Enter a SQL query that returns the entity's rows (e.g. SELECT * FROM main.default.person) and click Test Query to preview.
3. Choose the ID column (used to mint unique URIs) and a label column, then map each attribute to a result column. Save Mapping.
4. Click relationships to map them: a query returning source and target IDs, then pick the source/target ID columns.

Click Validate in the navbar to confirm every mapping is complete — the Mapping indicator turns green ✓. You can review the generated R2RML under Domain → Export.

5 Choose a backend & build the graph

Pick where the triples live, then materialize them — click 4.

1. Under Domain → Information → Knowledge Graph, choose a Graph Backend:
   • Lakebase (Postgres) — the default; fast, incremental.
   • Lakehouse — governed Unity Catalog Delta triple tables; nothing extra to provision.
   • Neo4j — native graph database over Bolt (Aura or self-hosted).
2. Go to Knowledge Graph → Build, then click Synchronize. OntoBricks executes your mappings and writes the triples to the chosen store (incremental by default).

6 Explore in the Graph Explorer (UI)

Open Knowledge Graph → Explorer to browse the materialized graph interactively in the WebGL viewer.

• Two-phase search — use Find to preview matching entities in a flat list, then select the ones to expand into the graph with their relationships and neighbours.
• Click a node to see all its attributes, values and relationships in the right-hand details panel.
• Right-click → "Expand neighbours" to enrich the view in place with N-hop neighbours (depth follows the right-pane Depth slider).
• Filters narrow the view by entity type, field, or depth; bridges let you jump across domains.
• Data cluster detection finds communities (Louvain, Label Propagation, Greedy Modularity) and can colour or collapse them into super-nodes.

7 Reason & validate (optional)

Turn the graph from stored facts into inferred knowledge:

• Inference (sidebar) — run OWL 2 RL deductive closure and your SWRL business rules to discover new, inferred triples; transitive and symmetric properties are expanded.
• Data Quality (sidebar) — validate the graph against SHACL shapes: cardinality, datatypes, patterns and custom rules, with a configurable per-rule violation cap.

Define these rules ahead of time under Ontology → Business Rules (a graphical SWRL editor) and Ontology → Data Quality (SHACL shapes).

8 Query with GraphQL

OntoBricks generates a typed GraphQL schema from your ontology at runtime — each class becomes a type, each attribute a field, each relationship a typed edge.

1. Open the Query section to reach the GraphiQL playground for this domain.
2. Traverse nested relationships in a single request, e.g.:

{
  allCustomer(limit: 3, search: "Martinez") {
    id
    label
    email
    hasInteraction {
      label
      date
    }
  }
}

9 Publish & expose the domain

External tools — the REST API and MCP — only serve a PUBLISHED version, and only when the domain is flagged for exposure.

1. Move the version through its lifecycle: DRAFT → IN-REVIEW → PUBLISHED. Submit for review from Domain → Validation; publish once the sign-off quorum is met (admins can publish directly).
2. In Domain → Information → Global, toggle Expose via API & MCP to ON. Domains without this flag are hidden from both the REST API and MCP.
3. Confirm on Domain → Validation (Cockpit): the Published Version tile shows exactly which version is being served over API / MCP.

10 Use it via MCP

OntoBricks exposes the graph to LLM agents through the Model Context Protocol. The companion mcp-ontobricks app forwards agent tool calls to your OntoBricks REST + GraphQL API.

In the Databricks Playground

1. Deploy the MCP server. It ships in the same bundle — make deploy deploys it as mcp-ontobricks (apps whose name starts with mcp- are auto-discoverable in the Playground). Start it if needed: databricks bundle run mcp_ontobricks_app -t <target>.
2. Open your workspace Playground and select mcp-ontobricks from the MCP Servers list.
3. Ask questions in natural language — e.g. "What entity types are in the graph?" or "Tell me about Jacob Martinez".

How the agent explores your graph

The tools follow a simple two-step flow — choose a domain, then query it:

• list_domains → select_domain — pick which exposed graph to work on.
• list_entity_types — overview of entity types, counts and predicates.
• describe_entity — full-text description of an entity: identity, attributes, relationships and neighbours (BFS traversal).
• get_entity_context / invoke_entity_action — linked UC datasets, cross-domain bridges, and Unity Catalog function actions bound to a class.
• get_graphql_schema → query_graphql — discover the typed schema, then run nested, filtered queries.

From Cursor or Claude Desktop

Point a local MCP client at the deployed app over Streamable HTTP:

{
  "mcpServers": {
    "ontobricks": {
      "type": "streamable-http",
      "url": "https://<mcp-ontobricks-app-url>/mcp"
    }
  }
}

See the MCP Server documentation for the full tool reference, stdio configuration, and MCP Inspector testing.

Next steps