Data Access Wrappers — Engine Map

This document inventories every way the OntoBricks platform reads (or asks the backend to read) data, and pins each user-facing feature to the underlying query engine(s) it ends up using.

The goal is to answer, for any feature in the UI, the MCP server, or the Graph Chat assistant: "when I click this, which engine actually runs?"

---

1. The five access wrappers

OntoBricks exposes data through five layered wrappers. Three are user-facing languages, two are engine-facing dialects the platform translates down to.

Supporting W3C standards (not query languages)

These layers shape queries but don't run them — they are mappings, constraints, and rule definitions:

---

2. Storage backends — which engine speaks which language

Which engine actually runs your query depends on the domain's configured triple-store backend (GraphDBFactory.create(...)):

The selection is made in back/core/graphdb/GraphDBFactory.py. Both engines share the single GraphDBBackend contract: the Delta view is the governance-controlled snapshot, and the Lakebase engine is the queryable mirror used by the Knowledge Graph, reasoning and BFS / cohort helpers. The user-facing wrappers (REST / GraphQL / SPARQL) don't change when the engine is swapped.

GraphDB engines. GraphDBBackend is the abstract base class; concrete engines live under back/core/graphdb/<engine>/. The currently shipped engine is Lakebase Postgres (back/core/graphdb/lakebase/); additional engines (e.g. KuzuDB, Neo4j, Memgraph) can be plugged in via GraphDBFactory using the _starter_kit/ExampleStore.py template, without changing any of the user-facing wrappers above.

---

3. Decision tree — which wrapper fires for what?

            "I want to ..."
                  │
        ┌─────────┴──────────────────────────────────────┐
        │                                                │
"... explore / browse / mutate"                "... read graph data"
   the registry, ontology,                              │
   mapping, permissions                                 │
        │                                  ┌────────────┼────────────────┐
        │                                  │            │                │
       REST                              SPARQL      GraphQL          Cypher
   (/api/v1/* or /dtwin/*)            (free-form    (typed,       (graph traversal,
                                       triples,     nested,        SWRL rules)
                                       aggregates,  schema-driven)       │
                                       analytics)                        │
                                                                  Internal only
                                                                 (GraphDB engine
                                                                  + reasoning)

---

4. UI features — engine map

Pages live under src/front/templates/ and src/front/static/<page>/js/.... Each row maps a UI feature to the wire protocol it speaks (column Wrapper) and the engine that ultimately runs (column Engine).

4.1 Registry & Domain

4.2 Ontology Designer

4.3 Mapping (R2RML)

4.4 Knowledge Graph (the core read surface)

This is where users actually query the graph viewer. Graph Viewer, GraphQL, and Graph Chat all sit under the Knowledge Graph menu; they hit different wrappers but eventually share the same Delta / GraphDB storage.

GET /dtwin/reasoning/inferred is a lightweight status call: it returns graph_name, materialized_inference_count, and purge_supported without serializing inferred triples. The nested reasoning.inferred_count and empty reasoning.inferred_triples fields remain for compatibility.

4.5 Settings / Teams / Help

---

5. MCP server (src/mcp-server) — engine map

The MCP server is a thin proxy over the OntoBricks public REST + GraphQL surface (/api/v1/... and /graphql/...). It runs as its own Databricks App, authenticates with an M2M OAuth token, and uses httpx.AsyncClient. It never speaks SPARQL or Cypher directly.

Per-domain policy. The first three tools are registry-level and always available. The rest are domain-scoped: a domain can hide any of them from Domain → Information → MCP, and can set its dataset / bridges / actions attachments to disabled. Because the MCP server is a proxy, the disabling is enforced at the endpoints above, not in the proxy — nodes/context and domain/classes omit the element, and nodes/action refuses. Hiding a tool is presentation on top of that, so a stale client that calls a hidden tool anyway gets a refusal instead of data. See Per-domain MCP policy.

Ontology-only domains. A domain can be published with an ontology but no Knowledge Graph build (no mapping, no graph). GET /api/v1/domains flags it with has_graph: false; on select_domain the MCP server hides every graph tool and exposes describe_ontology alone (plus the four registry-level tools). describe_ontology needs no graph — it serves the ontology schema — so it is always available and the call-time guard refuses the graph tools for such a domain even if a stale client calls them.

Note. MCP and the external REST/GraphQL API only see versions whose lifecycle status is PUBLISHED — they default to the numeric-latest PUBLISHED version and reject explicit requests for DRAFT/IN-REVIEW versions. A version becomes servable by transitioning it DRAFT → IN-REVIEW → PUBLISHED from Registry → Browse (this replaces the former "Active"/mcp_enabled toggle). To query an unsaved working session, use the Graph Chat (next section), which talks to the session-aware /dtwin/... internal routes instead.

---

6. Graph Chat (src/agents/agent_dtwin_chat) — engine map

The Graph Chat agent runs inside the OntoBricks process, talks to loopback (http://localhost:8000), forwards user session cookies + the Databricks Apps X-Forwarded-* headers, and targets the internal session-aware /dtwin/... routes. This means it works on unsaved domains and (uniquely) speaks SPARQL.

The system prompt steers the LLM's protocol choice:

• "Tell me about X" → describe_entity (REST/triples)
• "How many / group by / aggregate" → run_sparql (SPARQL → Spark SQL)
• "Customer + orders + products in one payload" → get_graphql_schema then query_graphql

---

7. Other LLM agents — engine map

These agents do not query the triple store at runtime; they operate on the design-time ontology / metadata.

Document reading (documents.read / read_document)

Both agent_owl_generator and agent_business_rules_generator read uploaded domain documents from the UC Volume via read_document:

• Plain text (.txt, .md, .json, .csv, .xml) is fetched through the Files API and decoded as UTF-8.
• Binary documents (.pdf, .docx, .pptx, images) are converted to markdown on the fly using the Databricks ai_parse_document SQL function (output schema pinned to v2.0): SELECT to_json(ai_parse_document(content, map('version', '2.0'))) FROM READ_FILES(<volume path>, format => 'binaryFile'). This runs on the configured SQL warehouse, so the warehouse identity (app service principal or user) must have READ VOLUME on the documents volume. The function returns a VARIANT (output schema v2.0, verified live): text is read from document.elements[].content (figures expose an AI-generated description); document.pages[] only carries id/image_uri. The extractor prefers elements and keeps page-content / markdown-blob fallbacks for other schema versions. The extraction engine is a generic, reusable class — back.core.databricks.DocumentExtractor (src/back/core/databricks/DocumentExtractor.py, exposing supports() / is_available() / extract() / extract_text_from_parsed()) — so it can be used outside the agents and swapped for a different parser without changing callers.
• When no SQL warehouse is configured, binary documents are skipped (the tool returns an explanatory message) and generation proceeds from metadata + text documents only. Parsed text is cached per file for the duration of an agent run and truncated to the per-document character cap.

---

8. Reasoning engine — engine map

The reasoning pipeline (back/core/reasoning/) chooses a translation target based on the active triple-store backend's query_dialect.

---

9. Three end-to-end query flows

9.1 User clicks Graph Chat → "How many Customers per Country?"

Browser  ──POST /dtwin/assistant/chat──▶  api/routers/internal/dtwin.py
                                                  │
                                                  ▼
                                       agent_dtwin_chat.engine.run_agent
                                                  │
                                                  │ tool_call: run_sparql
                                                  ▼
                          POST /dtwin/execute  (loopback HTTP, session cookies)
                                                  │
                                                  ▼
                                  SparqlTranslator (SPARQL → Spark SQL via R2RML)
                                                  │
                                                  ▼
                                  Databricks SQL Warehouse on Delta view
                                                  │
                                                  ▼
                                       rows → markdown table → reply

Wrappers in play: REST → SPARQL → Spark SQL.

9.2 External LLM (Cursor) calls MCP query_graphql

Cursor (stdio)  ──FastMCP──▶  src/mcp-server/server/app.py
                                       │
                                       ▼
                       POST /graphql/{domain}  (httpx, M2M OAuth bearer)
                                       │
                                       ▼
                    back/fastapi/graphql_routes.py → ResolverFactory
                                       │
                                       ▼
                              DomainQueryService (SPARQL)
                                       │
                                       ▼
                       Databricks SQL Warehouse on Delta view

Wrappers in play: REST (transport) → GraphQL (query) → SPARQL → Spark SQL.

9.3 User opens Graph Viewer tab and applies a filter

Browser  ──POST /dtwin/sync/filter──▶  api/routers/internal/dtwin.py
                                                │
                                                ▼
                                        DigitalTwin.filter()
                                                │
                                                │   backend = "view"          backend = "graph"
                                                ▼                                    ▼
                                  SparqlTranslator             GraphDBBackend.query(...)
                                  (SPARQL → Spark SQL)         (e.g. Lakebase Postgres)
                                                │                            │
                                                ▼                            ▼
                              Databricks SQL Warehouse           Lakebase flat table
                                                                  (Postgres SQL)
                                                │                            │
                                                └──────► triples ◀───────────┘
                                                            │
                                                            ▼
                                              Sigma.js renders the graph

Wrappers in play: REST → (SPARQL → Spark SQL on Delta) and Postgres SQL on the Lakebase Graph DB.

---

10. TL;DR matrix — what each surface exposes

User-visible query languages today: REST, GraphQL, SPARQL. Engine-side dialects the platform compiles down to: Spark SQL on the Delta view and Postgres SQL on the Lakebase Graph DB. The query_dialect flag on GraphDBBackend reserves a slot for plugging in a future Cypher / Gremlin engine.

---

11. Source-code anchors (quick links)

• REST routes — src/api/routers/internal/dtwin.py, src/api/routers/v1.py, src/api/external_app.py
• GraphQL — src/back/fastapi/graphql_routes.py, src/back/core/graphql/{GraphQLSchemaBuilder,ResolverFactory,SchemaMetadata}.py
• SPARQL — src/back/core/w3c/sparql/{SparqlTranslator,SparqlQueryRunner,DomainQueryService}.py
• Graph DB factory — src/back/core/graphdb/GraphDBFactory.py
• GraphDB backend — src/back/core/graphdb/GraphDBBackend.py
• Delta engine — src/back/core/graphdb/delta/DeltaFlatStore.py
• GraphDB engine (Lakebase Postgres) — src/back/core/graphdb/lakebase/{LakebaseBase,LakebaseFlatStore,SyncedTableManager}.py
• Reasoning — src/back/core/reasoning/{OWLRLReasoner,SWRLSQLTranslator,SPARQLRuleEngine,DecisionTableEngine,AggregateRuleEngine}.py
• MCP server — src/mcp-server/server/app.py, src/mcp-server/mcp_server.py
• Graph Chat — src/agents/agent_dtwin_chat/{engine,tools}.py