Ontology and semantic layer

Ontology lets workspace users define business-facing objects, dimensions, measures, and relationships over physical tables. Users edit an isolated working branch, submit changes for review, and merge approved changes to the project's main model. Cube compiles the effective project and branch model and executes semantic queries through Trino.

This assessment covers projects, objects, relationships, proposal review and merge, workbooks, the object graph, semantic-query execution, persistence, dynamic model loading, and the scale boundaries from Ontology through Cube and Trino. Workbooks and semantic queries are runtime consumers of the published model; they are not part of its immutable revision history.

See Architecture and evidence and reproduction.

Assessment scope

Field	Value
Actors	Model author, reviewer, project administrator, platform administrator, semantic-query consumer, and platform operator
Components assessed	sparqd/oqullus, sparqd/bff-api, sparqd/ontology, sparqd/platform-stacks, Cube, Trino, and KubeBlocks PostgreSQL
Assessed environment	Realm gj76anadpsc; workspace w-t5e2kcxjd; Kubernetes context dev-north-alicloud
Deployed baselines	ontology-backend e499673; BFF API 9b2fd45; Cube v1.6.38
Source baselines	Oqullus integration source f76e57db; platform-stacks a71390d; ontology origin/main 984932a compared with deployed e499673
Last verified	4 September 2026
Review status	Engineering assessment recorded; product, data-governance, security, and operations validation not recorded

The five ontology commits newer than the deployed backend add proposal email and build changes; they do not change the reviewed core object lifecycle.

Current lifecycle

1. Oqullus selects an Ontology project and branch. A project is currently a model namespace, not an authorization boundary.
2. The UI reads the effective branch model through BFF proxy routes.
3. An authenticated branch owner creates, updates, renames, or deletes objects on a writable working branch. PostgreSQL stores the branch overlay as JSON.
4. Backend validation checks model shape, member uniqueness, primary-key presence, relationship target existence, and balanced template braces. It does not validate physical tables, columns, SQL semantics, or Cube compilation.
5. Proposal merge publishes object projection, immutable object versions, main revision, proposal state, and notifications in one database transaction.
6. Reviewers inspect a live branch diff. Editing the branch rebuilds proposal tasks, removes existing decisions, and returns the proposal to Open.
7. Workbooks persist query configuration and selected dashboard tabs in the same PostgreSQL database. Results are not saved by the current UI; reopening a configured tab runs the query again.
8. The object graph fetches object summaries and then every visible object definition, builds edges from name-based relationships, and lays out the complete fetched subset in the browser.
9. Cube uses contextToAppId to isolate compiler state by project and branch, obtains generated YAML through repositoryFactory, and calls schemaVersion to detect changes.
10. Semantic queries use a short-lived Cube token containing the project, branch, and effective Trino username. Trino and Ranger remain responsible for physical data authorization.

There is no separate model deployment artifact. Publication is a database state transition; Cube pulls and compiles the selected effective model on demand.

Support boundary

Capability	Current state	Boundary
Projects	Available as shared model namespaces	No project membership or project-scoped authorization exists; treat isolation as an improvement backlog
Main model	Read-only in Oqullus	Deprecated direct-main POST and DELETE routes remain reachable through BFF
Working branches	Available	Mutations are branch-owner-only; concurrent writes from the same identity have no optimistic conflict check
Object validation	Structural validation available	Physical tables, columns, SQL expressions, and Cube compilation are not checked before merge
Relationships	Embedded in the source object	Targets must exist, but the database has no relationship foreign key because definitions are JSON documents
Proposal review	Author-separated approve/reject and admin merge are implemented	Impact is calculated in Oqullus from partial/fan-out reads, is discarded on failure, and is not an authoritative merge gate
Decision audit	Every decision row is retained in PostgreSQL	API/UI return only each reviewer's latest decision and omit decision/proposal timestamps
Workbooks	Query configuration, tabs, chart choice, and dashboard selection are persisted	Resource authorization is not enforced; save timing is implicit; writes are last-write-wins; dashboard tab references are JSON IDs
Workbook results	Queries rerun through Cube	Current Oqullus deliberately does not persist result_data; opening configured tabs or dashboards can execute queries again
Object graph	Available for the fetched project/branch subset	It inherits the first-50/N+1 object path and performs full Dagre layout and React rendering in the browser
Semantic query	Branch-aware Cube query builder and results/chart views are available	Default is No Limit; results are fully buffered and client-paged; browser Stop does not cancel upstream work
Model versioning	Main revisions and immutable object-version rows exist	The deployed workspace contains no representative object or proposal history
Cube model loading	Dynamic project/branch loading available	Dependency failures are converted to empty/default model state by deployment configuration
Cube execution topology	One API, one CubeStore router, and two CubeStore workers are deployed	Cache/queue driver is memory, refresh worker is disabled, generated models contain no pre-aggregations, and all CubeStore pods share one node
Trino query capacity	One fixed coordinator and one fixed worker are deployed	Worker autoscaling and workload admission are absent; semantic Cube traffic connects directly to the cluster rather than the autoscaled gateway
Object listing	Available for the first backend page	Oqullus never requests a second page; objects after the first 50 alphabetically are absent from list and search
Recovery	PostgreSQL is the model source of truth	One database replica, no declared backup, and destructive cluster termination policy
Schema migration	Alembic migrations exist	Deployment does not run or gate on them; the current database was nevertheless at image head when inspected

Validation policy

Recommended policy:

• Permit a structurally valid but datasource-unresolved draft on a working branch so authors can model incrementally.
• Record and display validation status, timestamp, datasource identity, and diagnostics on the draft.
• Require generated Cube model compilation plus table, column, relationship, and expression validation before proposal submission.
• Repeat authoritative validation immediately before merge to detect metadata drift between review and publication.
• Reject merge on blocking failures. Do not publish a model that has only been checked by the browser's metadata selectors.

Critical journeys

Journey	Required result
Create or edit a draft	Persist a structurally valid working-branch change without mutating main
Invalid model shape	Return field-specific validation without a partial write
Missing table or column	Preserve the draft if policy allows, mark it invalid, and block proposal or merge
Rename an object	Preserve stable object identity and update affected references atomically
Delete a referenced object	Reject deletion with the incoming relationships identified
Submit and merge	Revalidate against current metadata, publish one atomic main revision, and retain audit identity
Review destructive changes	Show complete, revision-bound relationship and workbook impact; never turn an impact-read failure into “no impact”
Change a review decision	Preserve and display the complete decision chronology while deriving one current effective state
Create, reopen, and edit a workbook	Enforce workspace/project/owner policy, disclose saved versus unsaved state, and prevent silent lost updates
Delete or reorder a workbook tab	Keep dashboard membership and positions valid in one transaction
Open a workbook dashboard	Bound concurrent query fan-out and expose each chart's queued/running/failed/cancelled state
Open and search the object graph	Display a complete authorized graph or an explicit bounded subgraph without blocking the browser
Run a semantic query	Apply a safe default and maximum result boundary, preserve project/branch/user identity, and expose queue and execution state
Cancel a semantic query	Propagate one correlated cancellation through Cube to Trino and confirm terminal engine state
Scale query service	Scale the saturated layer without fragmenting queues/caches or merely moving pressure downstream
Unauthorized project access	Apply the documented shared-namespace policy now and project membership when introduced
Ontology or Cube failure	Identify the failing dependency; do not present an empty model as a valid model
More than 50 objects	Page, search, and sort the complete authorized result set without N+1 detail calls
Database loss or migration failure	Restore the model source of truth and block rollout on incompatible schema

Findings

ID	Finding	Components	Evidence	Impact	Issue
GOV-ONT-001	Define projects as an authorization boundary when project isolation is introduced	Ontology backend, BFF API, Oqullus, identity policy	Source + deployed role mapping	Improvement backlog	ontology-backend#13
GOV-ONT-002	Retire deprecated direct-main mutation routes	Ontology backend, BFF API	Source + automated tests	High	ontology-backend#14
DATA-ONT-001	Validate model executability before publication	Ontology backend, Cube, Trino, Oqullus	Source-verified	High	ontology-backend#15
REL-ONT-001	Surface dynamic model dependency failures	Platform stacks, Cube, ontology backend, Oqullus	Source-verified	High	platform-stacks#680
OPS-ONT-001	Protect and test recovery of the Ontology source of truth	Platform stacks, KubeBlocks PostgreSQL, ontology backend	Live deployment + source	Critical	platform-stacks#681
PERF-ONT-001	Page and summarize the complete object list	Oqullus, ontology backend, BFF API	Source-verified	High beyond 50 objects	oqullus#549
OPS-ONT-002	Make schema migration a deployment gate	Platform stacks, ontology backend	Live revision + source	High	platform-stacks#682
SEC-ONT-001	Enforce workbook resource authorization	Ontology backend, BFF API, Oqullus	Source-verified; live negative test pending	Critical	Not opened
GOV-ONT-003	Make proposal impact authoritative and revision-bound	Ontology backend, Oqullus	Source-verified; representative proposal pending	High	Not opened
GOV-ONT-004	Expose complete proposal decision chronology	Ontology backend, Oqullus	Source-verified	Medium	Not opened
DATA-ONT-002	Define a safe workbook persistence and concurrency contract	Ontology backend, Oqullus	Source-verified; multi-session test pending	High	Not opened
PERF-ONT-002	Serve a complete bounded object-graph projection	Oqullus, ontology backend, BFF API	Source-verified; scale test pending	High	Not opened
REL-ONT-002	Propagate semantic-query cancellation to Trino	Oqullus, BFF API, ontology backend, Cube, Trino	Source-verified client gap; engine outcome pending	High	Not opened
PERF-ONT-003	Bound semantic-query result size end to end	Oqullus, BFF API, ontology backend, Cube, Trino	Source-verified; payload limit pending	High	Not opened
ARCH-ONT-001	Align Cube API, refresh worker, and CubeStore with the actual workload	Platform stacks, Cube, CubeStore, ontology backend	Deployed topology + source	High	Not opened
PERF-ONT-004	Bound model loading and compiler/orchestrator cardinality	Ontology backend, Cube, PostgreSQL, platform stacks	Source-verified; scale boundary pending	High	Not opened
PERF-ONT-005	Bound workbook listing and dashboard query fan-out	Oqullus, ontology backend, Cube, Trino	Source-verified; concurrency boundary pending	High	Not opened

Findings describe observed behavior and required decisions, not accepted implementation commitments. Existing issues are linked from their detailed findings; the new findings remain unfiled until review.

Assessment maturity

Scale: 0 absent, 1 ad hoc, 2 partly documented or automated, 3 routinely verified, 4 measured and improving.

Lens	Score	Evidence-backed assessment
Product and UX	1	Authoring, review, workbooks, graph, results, and charts exist; save/freshness/queue semantics and representative deployed journeys remain incomplete.
Architecture and data	2	Stable IDs, branch overlays, atomic merges, immutable main revisions, and Cube isolation exist; workbook integrity, publication validation, and runtime result boundaries remain incomplete.
Security and governance	1	Branch review roles exist, but project isolation is undefined, workbook routes lack resource authorization, decision chronology is hidden, and deprecated main writes remain.
Reliability and operations	1	Deployed components are healthy, but browser cancellation is not upstream cancellation, model-load failures are hidden, and recovery is not declared or tested.
Performance	1	No supported object, graph, workbook, branch, compiler-context, query-concurrency, or result-size boundary is stated; several paths materialize or fan out over complete sets.
Delivery and lifecycle	1	Exact deployed revisions are known, but migrations are not an enforced deployment step and component-owner validation is absent.

Current evidence limitation

The deployed database contained one active core project, its active main branch, revision zero, and zero objects, changes, proposals, decisions, proposal tasks, object versions, workbooks, or workbook tabs. Deployment topology and data shape are live-confirmed, but there is no representative model against which to claim deployed review, workbook, graph, semantic-query, rollback, or recovery behavior. Those journeys remain open until a controlled test model is created.