Orionbelt Semantic Layer

OrionBelt® Semantic and Context Layer, Rule Engine, and Semantic Sidecar

Define shared metrics or model a set of questions in YAML. Let agents and BI tools query through one semantic compiler.

A semantic sidecar : it rides alongside the systems you already run instead of replacing them.

---

Ask an LLM to write SQL against a raw star schema and sooner or later it joins two fact tables and hands you a revenue number inflated by a factor of eight. It looks right. Nobody catches it.

OrionBelt is a semantic and context layer with a rule engine, and it runs as a [semantic sidecar](https://ralforion.com/semantic-sidecar.html). You or an agent declare dimensions, measures, metrics, and joins in YAML, scoped to one task or maintained as a shared model. OrionBelt compiles them into dialect-specific SQL through a real AST, and routes multi-fact queries through a Composite Fact Layer planner that blocks the join paths that produce fan traps. Queries ask for "Total Revenue" by "Country"; physical table and column mappings live in the model.

No BI tool in the middle. No runtime lock-in. Point it at what you already have.

Model the questions

An agent can model just the questions it needs to answer. With POST /v1/oneshot/batch, it submits a task-specific OBML model and several independent queries in one request. OBSL validates the model, compiles or executes the queries, and returns separately identified results with SQL, explanations, warnings, and errors as applicable.

For "revenue by country, monthly revenue, and average order value," the agent defines the relevant columns and calculations once and asks three questions against them. A freshly loaded model is removed after the batch by default; persist_model: true keeps it in the session for follow-up questions. The same compiler supports this workflow and long-lived shared models.

Follow the agent workflow guide for a complete example, or see the one-shot API contract.

Four ways in

The same model serves every surface you already use. Four of them, and one model behind all four:

Both SQL surfaces speak OBSQL, so SELECT "Region", "Total Sales" FROM sales_model is the same query whichever one you came in through. ADBC is how you *use* the Flight SQL surface rather than a fifth surface of its own, and DuckDB is a client that can take either SQL surface.

Eight ways out

Compiles to BigQuery, ClickHouse, Databricks, Dremio, DuckDB/MotherDuck, MySQL, PostgreSQL, and Snowflake. The warehouse behind the model is independent of the surface in front of it: any of the four surfaces, against any of the eight dialects.

Here is TPC-DS query 98. Two measures over the same column, identical but for one line: Class Revenue is pinned to a coarser grain than the query asks for.

measures:

Store Sales Amount: columns: [{dataObject: Store Sales, column: Ext Sales Price}] aggregation: sum

Class Revenue: columns: [{dataObject: Store Sales, column: Ext Sales Price}] aggregation: sum grain: {mode: FIXED, keepOnly: [Class]} # <- pin to Class, ignore query grain

metrics: Revenue Ratio: expression: "{[Store Sales Amount]} * 100.0 / {[Class Revenue]}"

That one grain line is what becomes SUM(...) OVER (PARTITION BY "Class") below.

The query names business concepts. No tables, no joins, no SQL:

select:

dimensions: [Item ID, Item Description, Category, Class, Current Price] measures: [Store Sales Amount, Revenue Ratio] where:

• {field: Category, op: inlist, value: [Sports, Books, Home]}
• {field: Order Date, op: between, value: ["1999-02-22", "1999-03-24"]}

pip install orionbelt-semantic-layer

obsl compile tpcds.obml.yml -q Q98.yml -d duckdb

WITH "base" AS (

SELECT "Item"."i_item_id" AS "Item ID", "Item"."i_item_desc" AS "Item Description", "Item"."i_category" AS "Category", "Item"."i_class" AS "Class", "Item"."i_current_price" AS "Current Price", CAST(SUM("Store Sales"."ss_ext_sales_price") AS DECIMAL(18, 2)) AS "Store Sales Amount", SUM("Store Sales"."ss_ext_sales_price") AS "Class Revenue" FROM "main"."store_sales" AS "Store Sales" LEFT JOIN "main"."item" AS "Item" ON "Store Sales"."ss_item_sk" = "Item"."i_item_sk" LEFT JOIN "main"."date_dim" AS "Date" ON "Store Sales"."ss_sold_date_sk" = "Date"."d_date_sk" WHERE "Item"."i_category" IN ('Sports', 'Books', 'Home') AND "Date"."d_date" BETWEEN '1999-02-22' AND '1999-03-24' GROUP BY ALL ) SELECT "Item ID" AS "Item ID", "Item Description" AS "Item Description", "Category" AS "Category", "Class" AS "Class", "Current Price" AS "Current Price", "Store Sales Amount" AS "Store Sales Amount", "Store Sales Amount" * 100.0 / NULLIF(SUM("Class Revenue") OVER (PARTITION BY "Class"), 0) AS "Revenue Ratio" FROM "base" AS "base" ORDER BY "Category" ASC, "Class" ASC, "Item ID" ASC, "Item Description" ASC, "Revenue Ratio" ASC

You did not write the join path, the window function over an aggregate, the NULLIF guard, or one table name. Change -d duckdb to -d snowflake and the same two files compile for Snowflake, or for any of eight dialects.

This is checked, not asserted. 40 TPC-DS queries are built against a single OBML model and compared row by row against each engine's own reference SQL: 39 of 40 match on DuckDB at sf=1, 37 of 40 on ClickHouse at sf=10. Every one of the remaining differences traces to a reference variant rather than a compilation error, and each is documented. See the sweep, or the queries in examples/tpcds_queries/.

The same answer on every engine

Compiling for eight engines is the easy part. The engines disagree about results, and a layer that only fixes the spelling of a function passes the disagreement through to your dashboard or your agent. OrionBelt pins the answer:

Each row is executed against the live engines and asserted, not derived from vendor documentation. Set expressionMode: portable and a function outside the portable catalog becomes an error, so a model cannot pick up an engine dependency by accident.

Open and traceable

A semantic model should not be a dead end, and a number should be able to say where it came from.

• [Apache Ossie](https://ralforion.com/orionbelt-semantic-layer/guide/osi/) both ways. OSI (Open Semantic Interchange) is the open standard for portable semantic models, now developed as Apache Ossie (incubating). OrionBelt converts OBML to Ossie and back, with schema validation in both directions, over REST, the CLI (obsl convert) and the UI. The converter is also a standalone package (pip install osi-orionbelt) and is being contributed upstream.
• [Lineage](https://ralforion.com/orionbelt-semantic-layer/api/endpoints/#lineage) for every artefact and every query. What a dimension, measure, metric or rule is built from, and for a query the joins the planner actually chose, its multi-fact UNION ALL legs and exists subqueries, down to columns and tables. As JSON, Mermaid or Turtle, over REST, the CLI (obsl lineage) and the UI.
• [The model as a standard graph](https://ralforion.com/orionbelt-semantic-layer/guide/obsl/). Every loaded model exports as RDF (OWL, SHACL, SKOS, PROV) and answers read-only SPARQL, so *"which measures read this column?"* is a query rather than a code search, and lineage links into the same graph.

Where OrionBelt fits

OrionBelt is a sidecar, not a platform. It compiles a YAML model into correct SQL and exposes it over the protocols you already use. It does not run a cluster, own your cache, or ask you to adopt a cloud.

Reach for OrionBelt when:

• An agent needs to author a small model for a set of questions, submit the model and queries together, and optionally reuse it for follow-up analysis.
• Agents query your data and a silently wrong number is unacceptable. Multi-fact queries route through a Composite Fact Layer planner that blocks fan-trap join paths instead of quietly summing across them.
• You want your metric definitions in reviewable YAML, with no JavaScript or Python in the model layer.
• Your BI tool should connect over the Postgres driver it already ships, with no new connector to install and no vendor runtime in the path.
• You self-host, across more than one engine, and want one model to compile for all of them, with the same answer on each.
• You have