Skip to content
Semantic Operator

Semantic Operator

A Kubernetes operator for your semantic layer. Define a business metric once, and a compiler turns every request into exactly one governed SQL statement, so an agent, a dashboard, and an app all use the same certified definition.
QuickstartWhat a semantic layer isView on GitHub

Why agents get the number wrong

Section titled “Why agents get the number wrong”

Ask an agent for sales per employee. It joins stores to sales and adds up the headcount. That counts each store once for every sale it made, so the total is far too high.

Nothing fails. The query runs, the result is formatted neatly, and the number is off by about ten thousand times. Unless you already knew the right answer, you would ship it.

We tested 30 business questions, each asked three different ways.

Agent writes the SQL69%correct. All 28 misses ran without an error and returned a confidently wrong number.
Agent picks a certified metric97%correct, and the same question worded three ways gives the same answer.

The fix is not a better prompt. It is deciding once, in one place, what a metric means, and then never letting anything compute it another way.

See the full benchmark and method

Three pieces, running on Kubernetes

Section titled “Three pieces, running on Kubernetes”

A local CLI scaffolds the model

ossiectl, this project’s workstation CLI, reads your catalog and generates an Apache Ossie model. Tables, columns, and likely joins are filled in, and descriptions and PII tags can come from DataHub. You certify the metrics and the access rules.

The operator runs the lifecycle

Apply the model like any Kubernetes resource. It is validated, checked against the live database, compiled into a versioned artifact, and published. If a referenced table or column no longer exists, the new version is rejected and the last good one keeps serving.

The server plans and runs queries

One MCP or REST request becomes exactly one SQL statement, with access rules already applied. Agents connect over MCP and applications over REST. BI tools read governed SQL views created by the operator. The server is stateless, so it scales horizontally.

1 · Author · outside the clusterossiectlGlueDataHubPolaris / Hiveossiectlderive · validatemodel.yamlSemanticModelgit → kubectl2 · Reconcile · control planeSemantic Operatormanagervalidate · compiledrift · publishConfigMapversioned artifactwatchpublish3 · Serve · data planeSemantic ServerAgents · appsMCP · RESTserver × Nauthn · governplan · executeQuery engineStarRocks · Trinosemantic_viewsOPA · Rangeroptional external PDPwatch artifactone governed SELECTauthorize before plan or cacheview DDLdrift-check
Authoring happens once, by a person. Reconciliation and serving run continuously and independently. They coordinate through the Kubernetes API and never call each other, which is why queries keep being answered while the operator is upgrading.

Start here

Section titled “Start here”
What a semantic layer isWhy business meaning needs a home, and what breaks without one.
QuickstartInstall, load demo data, apply a model, run a governed query.
How it worksThe compiler, the reconcile loop, governance, and the extension points.
Authoring a modelGenerate a scaffold, then certify the metrics and access rules.
Developing and testingClone, build, run the offline suite, try changes on a cluster.
ExamplesWalkthroughs on StarRocks, Trino, Polaris, and a local laptop stack.

Bring your own engine

Section titled “Bring your own engine”

The engine is two pluggable halves chosen by one setting. StarRocks and Trino ship today, and the planner renders the SQL syntax required by each engine. Glue, Polaris, Hive Metastore, and Unity work through the engine’s own catalog, and your definitions stay portable because the model is plain Apache Ossie.

OssieOpen model format
YAMLConfiguration
Apache 2.0Open source
AI readyMCP native