ralforion/orionbelt-semantic-layer-api repository overview

⁠OrionBelt® Semantic and Context Layer, Rule Engine, and Semantic 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 and context layer with a rule engine, and it runs as 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.

⁠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/⁠.

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

⁠What is a Context Layer?

A semantic layer tells a consumer how to compute a number: which table, which join, which aggregate. A context layer also tells it what the number means and what the business expects of it, in a form an agent can look up instead of guess. In OrionBelt that context lives in the same model as the metrics:

• Business rules⁠ state conditions over the model's dimensions, measures and metrics: who counts as a high-value client, which categories must not sell at a loss. The rule engine compiles each rule to the query that reports its members or violations, and evaluates one rule or all of them over REST, MCP, the CLI (obsl rules evaluate) and the UI.
• External concept mappings⁠ link data objects, dimensions, measures, metrics and rules to the concepts your organisation already governs (schema.org, FIBO, an internal vocabulary), with provenance.
• The OBSL graph⁠ exposes every loaded model as RDF, so its artefacts, joins, rules and concept links can be queried with SPARQL.
• Lineage⁠ shows what a dimension, measure, metric, rule or query is built from, down to the tables and the joins the planner chose, as JSON, Mermaid, or Turtle linked into the OBSL graph, in the API, the CLI (obsl lineage) and the UI.
• Descriptions, synonyms and owners on each artefact give agents the vocabulary users actually speak.

Agents reach all of it over MCP and REST, next to the query tools, so the same model that computes a number can also explain it. The next section shows rules and concept links in a model.

⁠Meaning, not just metrics

A model that only knows that Total Sales is a sum still leaves the agent guessing what a high-value client is, or whether a category selling at a loss is a bug or a fact. Since 2.30 the model carries that too, and that is what makes OrionBelt a context layer as well as a semantic layer: business rules, links to the ontologies your organisation governs, and the model itself as an RDF graph give an agent the meaning behind the numbers, not only the numbers.

Business rules are conditions over the model's own dimensions, measures and metrics, with no SQL. The rule engine compiles each one to the query that reports its findings: the members of a classification or eligibility rule, the violations of a validation or constraint rule.

rules:
  Non-Negative Margin:
    type: validation
    severity: error
    description: Every product category must sell for at least what it cost
    grain: [Product Category]
    condition: {field: Gross Margin, op: ">=", value: 0}

This rule reads a metric, so it is aggregate: it becomes a HAVING at the category grain through the same planner as any query, multi-fact included. POST /v1/rules/{name}/evaluate returns the offending categories for this rule, and POST /v1/rules/evaluate runs every rule into one report.

Ontology links tie artefacts to the concepts your organisation already governs, as SKOS mapping relations with provenance:

ontology:
  prefixes:
    schema: "https://schema.org/"

dataObjects:
  Products:
    externalConceptMappings:
      - concept: schema:Product
        relation: exact
        justification: curated

Links never change the SQL. They change what can be asked: every loaded model is also an RDF graph, so "which artefacts mean a schema.org Product" is a SPARQL query, and the discovery API answers the same over REST (/concept-mappings, its /namespaces, and the /unmapped gap list).

For an agent this is the difference between guessing and looking it up. Over MCP, list_rules, evaluate_rule and find_concept_mappings sit next to execute_query as tools.

Guides: Business Rules⁠, External Concept Mappings⁠, OBSL Graph & SPARQL⁠.

⁠Contents

Four ways in⁠ · What is a Context Layer?⁠ · Meaning, not just metrics⁠ · 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⁠

⁠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

pip install orionbelt-semantic-layer

Then paste into a Python REPL:

from orionbelt.parser import ReferenceResolver, TrackedLoader
from orionbelt.compiler.pipeline import CompilationPipeline
from orionbelt.models.query import QueryObject, QuerySelect

model_yaml = """
version: 1.0
dataObjects:
  Orders:
    code: ORDERS
    columns:
      Price: { code: PRICE, abstractType: float }
      Country: { code: COUNTRY, abstractType: string }
dimensions:
  Country:
    dataObject: Orders
    column: Country
    resultType: string
measures:
  Total Revenue:
    resultType: float
    aggregation: sum
    expression: "{[Orders].[Price]}"
"""

loader = TrackedLoader()
raw, source_map = loader.load_string(model_yaml)
resolver = ReferenceResolver()
model, result = resolver.resolve(raw, source_map)

query = QueryObject(select=QuerySelect(dimensions=["Country"], measures=["Total Revenue"]))
pipeline = CompilationPipeline()
output = pipeline.compile(query, model, "postgres")
print(output.sql)

Output:

SELECT
  "Orders"."COUNTRY" AS "Country",
  CAST(SUM("Orders"."PRICE") AS NUMERIC(18, 2)) AS "Total Revenue"
FROM ORDERS AS "Orders"
GROUP BY "Orders"."COUNTRY"

No env file needed — the compilation pipeline is stateless.

Start the servers:

orionbelt-api                              # REST API on :8000 (Swagger UI at /docs, Gradio UI at /ui)
orionbelt-ui                               # standalone Gradio UI on :7860 (connects to API on :8000)
FLIGHT_ENABLED=true orionbelt-api          # API + Arrow Flight SQL on :8815 (DBeaver, Tableau, Power BI)
PGWIRE_ENABLED=true orionbelt-api          # API + PostgreSQL wire on :5432 (Tableau, DBeaver, Superset, psql, Dremio source)

⁠Option C2: Install with uv

uv pip install orionbelt-semantic-layer

uv run orionbelt-api                       # REST API on :8000 (Swagger UI at /docs, Gradio UI at /ui)
uv run orionbelt-ui                        # standalone Gradio UI on :7860 (connects to API on :8000)
FLIGHT_ENABLED=true uv run orionbelt-api   # API + Arrow Flight SQL on :8815 (DBeaver, Tableau, Power BI)
PGWIRE_ENABLED=true uv run orionbelt-api   # API + PostgreSQL wire on :5432 (Tableau, DBeaver, Superset, psql, Dremio source)

Use the obsl CLI (no server needed - compiles in-process):

obsl validate model.yaml                                  # lint a model (exit 1 on error, CI-friendly)
obsl compile model.yaml -q query.json -d snowflake        # print the generated SQL
obsl compile model.yaml --sql 'SELECT "Region", "Sales" FROM model'  # ... or from an OBSQL string
obsl describe model.yaml                                   # overview of data objects + artefacts
obsl diagram model.yaml                                    # Mermaid ER diagram
obsl convert obml-to-osi model.yaml                        # OBML -> OSI (and osi-to-obml)
obsl execute -q query.json --server http://host           # run against a deployed model (omit MODEL)

See the CLI guide⁠ for all commands.

Smoke-test the Flight SQL surface without a BI tool:

uv run python examples/obsql.py 'SELECT version()'
uv run python examples/obsql.py 'SHOW TABLES'
uv run python examples/obsql.py 'SELECT "Region", "Total Sales" FROM sales LIMIT 5'

# Multi-model deployment? Pick the model with -m:
uv run python examples/obsql.py -m sales 'SHOW TABLES'
uv run python examples/obsql.py --list   # discover loaded models via REST

⁠Try OBSQL in 30 seconds

OBSQL — OrionBelt Semantic QL — is the SQL surface BI tools and humans actually write. Bare labels, MEASURE() markers, or matching aggregate wrappers; aggregation-match validation; WITH ROLLUP / WITH CUBE; no escape hatch to raw warehouse SQL. Same language over Arrow Flight SQL (v2.4+) and PostgreSQL wire (v2.5+):

PGWIRE_ENABLED=true uv run orionbelt-api &

# Every BI tool already ships a Postgres ODBC/JDBC driver — point yours at :5432
psql "host=localhost port=5432 user=obsl dbname=sales sslmode=disable" \
  -c 'SELECT "Region", "Total Sales" LIMIT 5'

# All three measure forms compile to the same vendor SQL:
psql "..." -c 'SELECT "Region", "Total Sales"        FROM sales LIMIT 5'  -- bare
psql "..." -c 'SELECT "Region", MEASURE("Total Sales") FROM sales LIMIT 5'  -- explicit marker
psql "..." -c 'SELECT "Region", SUM("Total Sales")   FROM sales LIMIT 5'  -- matching aggregate

See the OBSQL reference⁠ for the full grammar.

⁠Option D: Docker

Stage 1 — Zero-config start (models loaded later via API or UI):

docker run -p 8080:8080 ralforion/orionbelt-semantic-layer-api

Open http://localhost:8080/docs⁠ to explore the API.

Stage 2 — Realistic setup with docker compose:

# docker-compose.yml
services:
  api:
    image: ralforion/orionbelt-semantic-layer-api:2.34.0
    ports: ["8080:8080"]
    env_file: .env
    volumes:
      - ./models:/app/models:ro
    environment:
      MODEL_FILES: /app/models/my-model.obml.yml

  ui:
    image: ralforion/orionbelt-semantic-layer-ui:2.34.0
    ports: ["7860:7860"]
    environment:
      API_BASE_URL: http://api:8080

docker compose up -d

See .env.template⁠ for the full environment variable reference.

⁠Claude Desktop / MCP

The MCP server is a separate thin client that delegates to the REST API:

orionbelt-semantic-layer-mcp⁠

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "orionbelt": {
      "command": "uvx",
      "args": ["orionbelt-semantic-layer-mcp"]
    }
  }
}

Also works with Copilot, Cursor, and Windsurf. See the MCP repo⁠ for full setup options.

⁠Why OrionBelt?

⁠Features

⁠Semantic Modeling

• OBML Format — YAML-based semantic models with data objects, dimensions, measures, metrics, and joins
• Cross-Schema Queries — model data objects across multiple databases and schemas in a single model
• Static Model Filters — mandatory WHERE conditions baked into the model, auto-applied with join extension
• Business Rules — declarative rules over dimensions, measures and metrics (classification, eligibility, validation, constraint) without SQL; compiled to the query that reports their findings, tested one at a time or all at once into a report, listed and evaluated from the UI's Business Rules tab
• OBSL Graph & SPARQL — RDF graph export and read-only SPARQL querying for every loaded model; external concept mappings link data objects, dimensions, measures and metrics to a business ontology (FIBO, schema.org, a corporate glossary) as SKOS matches
• OSI Interoperability — bidirectional conversion between OBML and the Open Semantic Interchange format, now developed as Apache Ossie (incubating)⁠

⁠SQL Compilation

• 8 SQL Dialects — BigQuery, ClickHouse, Databricks, Dremio, DuckDB/MotherDuck, MySQL, Postgres, Snowflake
• AST-Based Generation — custom SQL AST ensures correct, injection-safe SQL (not string templates)
• Star Schema & CFL — automatic join resolution with Composite Fact Layer for multi-fact queries
• Data Types & Precision — automatic CAST wrapping with dialect-specific type rendering and precision clamping
• Display Formatting — number format patterns (#,##0.00, 0.00%) on measures/metrics with locale-aware rendering
• Timezone Settings — auto-detect database session timezone