OrionBelt® Semantic Layer and Sidecar

Define your metrics once in YAML. Let agents and BI tools query them without ever touching your schema.

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 sidecar. You declare dimensions, measures, metrics, and joins in version-controlled YAML. 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. Agents and BI tools ask for "Total Revenue" by "Country". They never see a table name.

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

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 model serves every surface you already use:

• Your BI tool, over the PostgreSQL wire protocol on :5432. Tableau, Power BI, Superset, DBeaver, and psql connect with the Postgres driver they already ship. Dremio federates it as a Postgres source.
• Your AI agents, over MCP. Works with Claude, Cursor, Copilot, and Windsurf.
• Your code, over REST, Arrow Flight SQL, or PEP 249 drivers.

Compiles to BigQuery, ClickHouse, Databricks, Dremio, DuckDB/MotherDuck, MySQL, PostgreSQL, and Snowflake.

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:

• 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.

Reach for something else when:

• You need pre-aggregation and caching tuned for high-concurrency dashboards at scale. Cube has years of production hardening there that OrionBelt does not.
• Your metrics already live in dbt and your team is happy there. MetricFlow keeps them where they are.
• You want an exploratory analysis language rather than a serving layer. Malloy is a better fit.

Try the live demo with a pre-loaded model, or open the Colab notebook and run it against TPC-H data.

Contents

Try it in 30 seconds · Claude Desktop / MCP · Why OrionBelt? · Features · Example · Documentation · Roadmap · Commercial · Development

Try it in 30 Seconds

Option A: Live Demo (no install)

Open the Live Demo — Gradio UI with a pre-loaded example model. Paste a query, pick a dialect, see SQL instantly.

API explorer: Swagger UI | ReDoc

Want to try the PostgreSQL wire surface? Cloud Run is HTTPS-only, so the public demo can't expose ports 5432 (pgwire) or 8815 (Flight SQL). Spin the same demo up locally in two commands — it includes the baked-in orionbelt_1_commerce DuckDB dataset and the full OBSQL surface:

Terminal

Copy

docker run --rm -d --name orionbelt-demo \
  -p 8080:8080 -p 5432:5432 -p 8815:8815 \
  -e PGWIRE_ENABLED=true \
  -e FLIGHT_ENABLED=true \
  ralforion/orionbelt-semantic-layer-api:latest

# REST + Gradio UI:   http://localhost:8080/ui
# pgwire (any psql / DBeaver / Tableau / Power BI):
psql "host=localhost port=5432 user=obsl dbname=orionbelt_1_commerce sslmode=disable" \
  -c 'SELECT "Client Name", "Total Sales" LIMIT 5'
# Flight SQL smoke test:
uv run python examples/obsql.py 'SELECT "Client Name", "Total Sales" LIMIT 5'

docker stop orionbelt-demo

The container ships with PGWIRE_AUTH_MODE=trust (default), so it's safe for localhost but not safe to expose to the public internet. For exposed deployments, set AUTH_MODE=api_key (shipped in v2.12.0): pgwire then negotiates SCRAM-SHA-256 (or cleartext over TLS) against the shared key store.

Option B: Google Colab (no install)

— Interactive notebook with TPC-H data: explore the model, compile queries across dialects, execute against DuckDB, and see results. Requires Python 3.12 runtime.

Option C: Install from PyPI