orionbelt-semantic-layer 1.6.2

OrionBelt Semantic Layer - Compiles and executes YAML semantic models as analytical SQL

OrionBelt Semantic Layer

Compile and execute YAML semantic models as analytical SQL across multiple database dialects

OrionBelt Semantic Layer is an API-first semantic engine and query planner for AI agents that compiles and executes declarative YAML model definitions as optimized SQL for BigQuery, ClickHouse, Databricks, Dremio, DuckDB/MotherDuck, MySQL, Postgres, and Snowflake. Query using business concepts — dimensions, measures, and metrics — instead of raw SQL.

Analytics as Code — Define your analytical semantics in version-controlled YAML, compile to dialect-specific SQL, and execute against live databases, all through a single API. No BI tool in the middle: the full loop from declarative model to query results is programmable, reviewable, and reproducible.

Features

• 8 SQL Dialects — BigQuery, ClickHouse, Databricks, Dremio, DuckDB/MotherDuck, MySQL, Postgres, Snowflake
• OBML Model Format — YAML-based semantic models with data objects, dimensions, measures, metrics, and joins
• AST-Based SQL — Custom SQL AST ensures correct, injection-safe SQL generation
• 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, applied to every query with auto-join extension
• Star Schema & CFL — Automatic join resolution with Composite Fact Layer for multi-fact queries
• REST API — FastAPI endpoints for model management, validation, compilation, and execution
• Gradio UI — Interactive web interface for model editing, query testing, and ER diagrams
• MCP Server — Available as a separate thin client for Claude, Copilot, Cursor, Windsurf
• AI Integrations — LangChain, OpenAI Agents SDK, CrewAI, Google ADK, Vercel AI SDK, n8n, ChatGPT
• DB-API 2.0 + Flight SQL — PEP 249 drivers and Arrow Flight SQL server for DBeaver, Tableau, Power BI
• OBSL Graph & SPARQL — RDF graph export and read-only SPARQL querying for every loaded model
• OSI Interoperability — Bidirectional conversion between OBML and Open Semantic Interchange format

Quick Start

Docker (fastest)

# API only
docker run -p 8080:8080 ralforion/orionbelt-api

# API + Gradio UI (two containers)
docker run -p 8080:8080 ralforion/orionbelt-api
docker run -p 7860:7860 -e API_BASE_URL=http://host.docker.internal:8080 ralforion/orionbelt-ui

# API + Flight SQL + Gradio UI (all-in-one image)
docker run -p 8080:8080 -p 8815:8815 ralforion/orionbelt-flight
docker run -p 7860:7860 -e API_BASE_URL=http://host.docker.internal:8080 ralforion/orionbelt-ui

API at http://localhost:8080 — Swagger docs at /docs — UI at http://localhost:7860

From Source

git clone https://github.com/ralfbecher/orionbelt-semantic-layer.git
cd orionbelt-semantic-layer
uv sync
uv run orionbelt-api

API at http://localhost:8000 — Swagger docs at /docs

Live Demo

http://35.187.174.102/ui — Gradio UI with pre-loaded example model

API: http://35.187.174.102 — Swagger UI | ReDoc

Example

Define a Semantic Model (OBML)

version: 1.0
dataObjects:
  Customers:
    code: CUSTOMERS
    database: WAREHOUSE
    schema: PUBLIC
    columns:
      Customer ID: { code: CUSTOMER_ID, abstractType: string }
      Country:     { code: COUNTRY, abstractType: string }

  Orders:
    code: ORDERS
    database: WAREHOUSE
    schema: PUBLIC
    columns:
      Order Customer ID: { code: CUSTOMER_ID, abstractType: string }
      Price:             { code: PRICE, abstractType: float }
      Quantity:          { code: QUANTITY, abstractType: int }
    joins:
      - joinType: many-to-one
        joinTo: Customers
        columnsFrom: [Order Customer ID]
        columnsTo: [Customer ID]

dimensions:
  Country:
    dataObject: Customers
    column: Country
    resultType: string

measures:
  Revenue:
    resultType: float
    aggregation: sum
    expression: "{[Orders].[Price]} * {[Orders].[Quantity]}"

Compile via REST API

# Create a session
curl -s -X POST http://localhost:8000/v1/sessions | jq .session_id
# -> "a1b2c3d4"

# Load the model
curl -s -X POST http://localhost:8000/v1/sessions/a1b2c3d4/models \
  -H "Content-Type: application/json" \
  -d '{"model_yaml": "..."}' | jq .model_id
# -> "abcd1234"

# Compile a query
curl -s -X POST http://localhost:8000/v1/sessions/a1b2c3d4/query/sql \
  -H "Content-Type: application/json" \
  -d '{"model_id":"abcd1234","query":{"select":{"dimensions":["Country"],"measures":["Revenue"]}},"dialect":"postgres"}' \
  | jq -r .sql

Generated SQL (Postgres):

SELECT
  "Customers"."COUNTRY" AS "Country",
  SUM("Orders"."PRICE" * "Orders"."QUANTITY") AS "Revenue"
FROM WAREHOUSE.PUBLIC.ORDERS AS "Orders"
LEFT JOIN WAREHOUSE.PUBLIC.CUSTOMERS AS "Customers"
  ON "Orders"."CUSTOMER_ID" = "Customers"."CUSTOMER_ID"
GROUP BY "Customers"."COUNTRY"

Change dialect to bigquery, clickhouse, databricks, dremio, duckdb, mysql, or snowflake for dialect-specific SQL.

Gradio UI

• SQL Compiler — side-by-side OBML model and query editors with syntax highlighting, 8 dialect selector, one-click compilation with formatted SQL output and query explain
• Query Execution — execute compiled queries against a connected database, view results in a scrollable data table with CSV download and clipboard copy (requires QUERY_EXECUTE=true)
• ER Diagram — interactive Mermaid ER diagram with zoom, column toggle, and download (MD/PNG/Turtle)
• Editor Toolbar — clear, undo, redo, upload, download, and copy buttons on all code editors
• OSI Import/Export — convert between OBML and OSI formats
• Dark/Light Mode — toggle via header button, state persisted across sessions

Embedded mode — the UI is mounted at /ui on the API server:

uv sync && uv run orionbelt-api
# -> UI at http://localhost:8000/ui

Standalone mode — run API and UI as separate processes:

uv sync
uv run orionbelt-api                                          # API on :8000
uv run orionbelt-ui                                           # UI on :7860 (connects to API on :8000)
API_BASE_URL=http://remote-api:8080 uv run orionbelt-ui       # point UI to a remote API

Documentation

Topic	Link
Full docs site	ralforion.com/orionbelt-semantic-layer
Installation	getting-started/installation
Quick Start	getting-started/quickstart
Docker & Deployment	getting-started/docker
Development	getting-started/development
OBML Model Format	guide/model-format
Query Language	guide/query-language
SQL Dialects	guide/dialects
Period-over-Period Metrics	guide/period-over-period
Compilation Pipeline	guide/compilation
OBSL Graph & SPARQL	guide/obsl
Gradio UI	guide/ui
AI Integrations	guide/integrations
OSI Interoperability	guide/osi
REST API Endpoints	api/endpoints
DB-API Drivers & Flight SQL	drivers
Architecture	reference/architecture
Configuration	reference/configuration
Sales Model Walkthrough	examples/sales-model
Multi-Dialect Output	examples/multi-dialect
Multi-Fact: Sales & Returns	examples/multi-fact
TPC-DS Benchmark	examples/tpcds
Quickstart Notebook	examples/quickstart.ipynb

Companion Project

OrionBelt Analytics

An ontology-based MCP server that analyzes relational database schemas and generates RDF/OWL ontologies. Together with OrionBelt Semantic Layer, it enables AI assistants to navigate your data landscape through ontologies and compile safe, dialect-aware analytical SQL.

License

Copyright 2025 RALFORION d.o.o.

Licensed under the Business Source License 1.1. The Licensed Work will convert to Apache License 2.0 on 2030-03-16.

By contributing to this project, you agree to the Contributor License Agreement.

---