Skip to content
Back to search

orionbelt-semantic-layer

Source-available semantic and context layer, rule engine, and semantic sidecar for agentic AI and governed analytics. Compiles declarative YAML models into optimized SQL, KPIs, and semantic context across 8 SQL dialects.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ralforion/orionbelt-semantic-layer with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ralforion/orionbelt-semantic-layer'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ralforion--orionbelt-semantic-layer/badge.svg)](/listings/ralforion--orionbelt-semantic-layer)

HTML

<a href="/listings/ralforion--orionbelt-semantic-layer"><img src="/api/listings/ralforion--orionbelt-semantic-layer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 804 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer/main/docs/assets/ORIONBELT_Logo.png" alt="OrionBelt Semantic Layer logo" width="320">
  3. </p>
  4. <h1 align="center">OrionBelt&reg; Semantic and Context Layer, Rule Engine, and Semantic Sidecar</h1>
  5. <p align="center"><strong>Define shared metrics or model a set of questions in YAML. Let agents and BI tools query through one semantic compiler.</strong></p>
  6. <p align="center">A <a href="https://ralforion.com/semantic-sidecar.html">semantic sidecar</a>: it rides alongside the systems you already run instead of replacing them.</p>
  7. <p align="center">
  8. <a href="https://orionbelt.ralforion.com/ui/?__theme=dark"><img src="https://img.shields.io/badge/Live_Demo-Try_it_now-brightgreen?style=for-the-badge" alt="Live Demo"></a>
  9. </p>
  10. <p align="center">
  11. <a href="https://github.com/ralforion/orionbelt-semantic-layer/releases"><img src="https://img.shields.io/badge/version-3.1.0-purple.svg" alt="Version 3.1.0"></a>
  12. <a href="https://pypi.org/project/orionbelt-semantic-layer/"><img src="https://img.shields.io/pypi/v/orionbelt-semantic-layer?logo=pypi&logoColor=white" alt="PyPI"></a>
  13. <a href="https://hub.docker.com/r/ralforion/orionbelt-semantic-layer-api"><img src="https://img.shields.io/docker/pulls/ralforion/orionbelt-semantic-layer-api?logo=docker&logoColor=white&color=2496ED" alt="Docker pulls"></a>
  14. <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
  15. <a href="https://github.com/ralforion/orionbelt-semantic-layer/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-BUSL--1.1-orange.svg" alt="License: BUSL-1.1"></a>
  16. </p>
  17. ---
  18. 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.
  19. 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](https://ralforion.com/text-to-sql.html). Queries ask for `"Total Revenue" by "Country"`; physical table and column mappings live in the model.
  20. No BI tool in the middle. No runtime lock-in. Point it at what you already have.
  21. ## Model the questions
  22. **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.
  23. 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.
  24. [Follow the agent workflow guide](https://ralforion.com/orionbelt-semantic-layer/guide/agent-workflows/) for a complete example, or see the [one-shot API contract](https://ralforion.com/orionbelt-semantic-layer/api/endpoints/#one-shot-batch).
  25. ## Four ways in
  26. The same model serves every surface you already use. Four of them, and one model behind all four:
  27. | Surface | Port | Speaks | Connect with |
  28. |---|---|---|---|
  29. | **PostgreSQL wire** | `5432` | Postgres protocol | [DuckDB](https://ralforion.com/orionbelt-semantic-layer/guide/duckdb/) via `ATTACH`, Tableau, [Dremio](https://ralforion.com/orionbelt-semantic-layer/guide/postgres-wire-bi-tools/#6-dremio-sql-runner-catalog-flip-calcite-quirks) as a federated source, Power BI, Superset, DBeaver, Metabase, `psql` |
  30. | **Arrow Flight SQL** | `8815` | gRPC + Arrow | [DuckDB](https://ralforion.com/orionbelt-semantic-layer/guide/duckdb/) via `adbc_scanner`, Tableau and Power BI through the Flight SQL JDBC/ODBC drivers, [ADBC](https://ralforion.com/orionbelt-semantic-layer/guide/adbc/) clients (Python, Go, Java) |
  31. | **REST** | `8000` | HTTP + JSON | your code, notebooks, `curl`, and the [8 PEP 249 drivers](https://ralforion.com/orionbelt-semantic-layer/drivers/) (which compile here, then execute on the warehouse directly) |
  32. | **MCP** | stdio / HTTP | Model Context Protocol | [AI agents](https://ralforion.com/agentic-ai-data-access.html): Claude, Cursor, Copilot, Windsurf |
  33. Both SQL surfaces speak [OBSQL](https://ralforion.com/orionbelt-semantic-layer/guide/semantic-ql/), 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.
  34. ## Eight ways out
  35. 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.
  36. **One query across databases (v3.0.0+).** A model's data objects can live in different databases, the orders in MySQL and the customers in PostgreSQL. A query that reads both is split into one query per database, run at once, and combined in an in-memory DuckDB. It returns the answer one database holding all the tables would return, or a named `FEDERATION_*` error, with a few exceptions that are not refused: text and NULL sorting, time zones, and text join keys between two engines that differ only in case, which MySQL matches and the combine step does not. See [Federated queries](https://ralforion.com/orionbelt-semantic-layer/guide/federation/) and the [results that can differ](https://ralforion.com/orionbelt-semantic-layer/guide/federation/#results-that-can-differ-from-one-database).
  37. **Files and lakehouse tables, no warehouse needed (v3.1.0+).** A DuckDB data source reads Parquet, CSV and JSON files where they are, on disk or in S3-compatible object storage, and Apache Iceberg tables behind a REST catalog. The model's dialect is `duckdb`; `DUCKDB_ALLOWED_PATHS` lists what a source may read, and `DUCKDB_MEMORY_LIMIT` bounds its memory. When one source's load needs more than one process, its queries can run on DuckDB workers. See [Files and lakehouse tables](https://ralforion.com/orionbelt-semantic-layer/guide/files-and-lakehouse/) and [DuckDB workers](https://ralforion.com/orionbelt-semantic-layer/guide/duckdb-workers/).
  38. 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.
  39. ```yaml
  40. measures:
  41. Store Sales Amount:
  42. columns: [{dataObject: Store Sales, column: Ext Sales Price}]
  43. aggregation: sum
  44. Class Revenue:
  45. columns: [{dataObject: Store Sales, column: Ext Sales Price}]
  46. aggregation: sum
  47. grain: {mode: FIXED, keepOnly: [Class]} # <- pin to Class, ignore query grain
  48. metrics:
  49. Revenue Ratio:
  50. expression: "{[Store Sales Amount]} * 100.0 / {[Class Revenue]}"
  51. ```
  52. That one `grain` line is what becomes `SUM(...) OVER (PARTITION BY "Class")` below.
  53. The query names business concepts. No tables, no joins, no SQL:
  54. ```yaml
  55. select:
  56. dimensions: [Item ID, Item Description, Category, Class, Current Price]
  57. measures: [Store Sales Amount, Revenue Ratio]
  58. where:
  59. - {field: Category, op: inlist, value: [Sports, Books, Home]}
  60. - {field: Order Date, op: between, value: ["1999-02-22", "1999-03-24"]}
  61. ```
  62. ```bash
  63. pip install orionbelt-semantic-layer
  64. obsl compile tpcds.obml.yml -q Q98.yml -d duckdb
  65. ```
  66. ```sql
  67. WITH "base" AS (
  68. SELECT
  69. "Item"."i_item_id" AS "Item ID",
  70. "Item"."i_item_desc" AS "Item Description",
  71. "Item"."i_category" AS "Category",
  72. "Item"."i_class" AS "Class",
  73. "Item"."i_current_price" AS "Current Price",
  74. CAST(SUM("Store Sales"."ss_ext_sales_price") AS DECIMAL(18, 2)) AS "Store Sales Amount",
  75. SUM("Store Sales"."ss_ext_sales_price") AS "Class Revenue"
  76. FROM "main"."store_sales" AS "Store Sales"
  77. LEFT JOIN "main"."item" AS "Item"
  78. ON "Store Sales"."ss_item_sk" = "Item"."i_item_sk"
  79. LEFT JOIN "main"."date_dim" AS "Date"
  80. ON "Store Sales"."ss_sold_date_sk" = "Date"."d_date_sk"
  81. WHERE
  82. "Item"."i_category" IN ('Sports', 'Books', 'Home')
  83. AND "Date"."d_date" BETWEEN '1999-02-22' AND '1999-03-24'
  84. GROUP BY ALL
  85. )
  86. SELECT
  87. "Item ID" AS "Item ID",
  88. "Item Description" AS "Item Description",
  89. "Category" AS "Category",
  90. "Class" AS "Class",
  91. "Current Price" AS "Current Price",
  92. "Store Sales Amount" AS "Store Sales Amount",
  93. "Store Sales Amount" * 100.0 / NULLIF(SUM("Class Revenue") OVER (PARTITION BY "Class"), 0) AS "Revenue Ratio"
  94. FROM "base" AS "base"
  95. ORDER BY
  96. "Category" ASC,
  97. "Class" ASC,
  98. "Item ID" ASC,
  99. "Item Description" ASC,
  100. "Revenue Ratio" ASC
  101. ```
  102. 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.
  103. **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](https://ralforion.com/orionbelt-semantic-layer/examples/tpcds-sweep/), or the queries in [`examples/tpcds_queries/`](examples/tpcds_queries/).
  104. ### The same answer on every engine
  105. 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:
  106. | Expression | What the engines do | What OrionBelt returns |
  107. |---|---|---|
  108. | `x / 0` | `inf` on one engine, an error on four, NULL on the rest | NULL, everywhere |
  109. | `round(2.5)` on a float | ClickHouse, PostgreSQL and MySQL round ties to even and answer 2 | 3, everywhere |
  110. | `greatest(1, NULL, 3)` | Four engines skip the NULL and answer 3 | NULL, everywhere |
  111. | `length('äbcd')` | ClickHouse and MySQL count bytes and answer 5 | 4 characters |
  112. | `json_value(doc, '$.a')` where `a` is an object | Four engines return the serialized JSON | NULL: the path did not reach a scalar |
  113. 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](https://ralforion.com/orionbelt-semantic-layer/comparison/#what-portable-means-here) becomes an error, so a model cannot pick up an engine dependency by accident.
  114. ## Open and traceable
  115. A semantic model should not be a dead end, and a number should be able to say where it came from.
  116. - **[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)](https://github.com/apache/ossie). 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.
  117. - **[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.
  118. - **[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.
  119. ## Where OrionBelt fits
  120. 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.
  121. **Reach for OrionBelt when:**
  122. - 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.
  123. - 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.
  124. - You want your metric definitions in reviewable YAML, with no JavaScript or Python in the model layer.
  125. - 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.
  126. - You self-host, across more than one engine, and want one model to compile for all of them, with the same answer on each.
  127. - You have to show where a number came from: which columns, which tables, and which join path the query took.
  128. - Your model has to move between tools rather than live in one, through Apache Ossie or as an RDF graph.
  129. **Reach for something else when:**
  130. - You need pre-aggregation and caching tuned for high-concurrency dashboards at scale. [Cube](https://cube.dev) has years of production hardening there that OrionBelt does not.
  131. - Your metrics already live in dbt and your team is happy there. [MetricFlow](https://github.com/dbt-labs/metricflow) keeps them where they are.
  132. - You want an exploratory analysis language rather than a serving layer. [Malloy](https://www.malloydata.dev) is a better fit.
  133. **[Try the live demo](https://orionbelt.ralforion.com/ui/?__theme=dark)** with a pre-loaded model, or [open the Colab notebook](https://colab.research.google.com/github/ralforion/orionbelt-semantic-layer/blob/main/examples/quickstart_colab.ipynb) and run it against TPC-H data.
  134. ## What is a Context Layer?
  135. 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:
  136. - **[Business rules](https://ralforion.com/orionbelt-semantic-layer/guide/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.
  137. - **[External concept mappings](https://ralforion.com/orionbelt-semantic-layer/guide/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.
  138. - **[The OBSL graph](https://ralforion.com/orionbelt-semantic-layer/guide/obsl/)** exposes every loaded model as RDF, so its artefacts, joins, rules and concept links can be queried with SPARQL.
  139. - **[Lineage](https://ralforion.com/orionbelt-semantic-layer/api/endpoints/#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.
  140. - **Descriptions, synonyms and owners** on each artefact give agents the vocabulary users actually speak.
  141. 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.
  142. ## Meaning, not just metrics
  143. 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.
  144. **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.
  145. ```yaml
  146. rules:
  147. Non-Negative Margin:
  148. type: validation
  149. severity: error
  150. description: Every product category must sell for at least what it cost
  151. grain: [Product Category]
  152. condition: {field: Gross Margin, op: ">=", value: 0}
  153. ```
  154. 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.
  155. **Ontology links** tie artefacts to the concepts your organisation already governs, as SKOS mapping relations with provenance:
  156. ```yaml
  157. ontology:
  158. prefixes:
  159. schema: "https://schema.org/"
  160. dataObjects:
  161. Products:
  162. externalConceptMappings:
  163. - concept: schema:Product
  164. relation: exact
  165. justification: curated
  166. ```
  167. 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).
  168. 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.
  169. Guides: [Business Rules](https://ralforion.com/orionbelt-semantic-layer/guide/business-rules/), [External Concept Mappings](https://ralforion.com/orionbelt-semantic-layer/guide/concept-mappings/), [OBSL Graph & SPARQL](https://ralforion.com/orionbelt-semantic-layer/guide/obsl/).
  170. ## Contents
  171. [Model the questions](#model-the-questions) · [Four ways in](#four-ways-in) · [Eight ways out](#eight-ways-out) · [Open and traceable](#open-and-traceable) · [What is a Context Layer?](#what-is-a-context-layer) · [Meaning, not just metrics](#meaning-not-just-metrics) · [Try it in 30 seconds](#try-it-in-30-seconds) · [Claude Desktop / MCP](#claude-desktop--mcp) · [Why OrionBelt?](#why-orionbelt) · [Features](#features) · [Example](#example) · [Documentation](#documentation) · [Roadmap](#status--roadmap) · [Commercial](#commercial-offerings) · [Development](#development)
  172. ---
  173. ## Try it in 30 Seconds
  174. ### Option A: Live Demo (no install)
  175. **[Open the Live Demo](https://orionbelt.ralforion.com/ui/?__theme=dark)** — Gradio UI with a pre-loaded example model. Paste a query, pick a dialect, see SQL instantly.
  176. API explorer: [Swagger UI](https://orionbelt.ralforion.com/docs) | [ReDoc](https://orionbelt.ralforion.com/redoc)
  177. > **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:
  178. >
  179. > ```bash
  180. > docker run --rm -d --name orionbelt-demo \
  181. > -p 8080:8080 -p 5432:5432 -p 8815:8815 \
  182. > -e PGWIRE_ENABLED=true \
  183. > -e FLIGHT_ENABLED=true \
  184. > ralforion/orionbelt-semantic-layer-api:latest
  185. >
  186. > # REST + Gradio UI: http://localhost:8080/ui
  187. > # pgwire (any psql / DBeaver / Tableau / Power BI):
  188. > psql "host=localhost port=5432 user=obsl dbname=orionbelt_1_commerce sslmode=disable" \
  189. > -c 'SELECT "Client Name", "Total Sales" LIMIT 5'
  190. > # Flight SQL smoke test:
  191. > uv run python examples/obsql.py 'SELECT "Client Name", "Total Sales" LIMIT 5'
  192. >
  193. > docker stop orionbelt-demo
  194. > ```
  195. >
  196. > 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.
  197. ### Option B: Google Colab (no install)
  198. [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ralforion/orionbelt-semantic-layer/blob/main/examples/quickstart_colab.ipynb) — Interactive notebook with TPC-H data: explore the model, compile queries across dialects, execute against DuckDB, and see results. Requires Python 3.12 runtime.
  199. ### Option C: Install from PyPI
  200. ```bash
  201. pip install orionbelt-semantic-layer
  202. ```
  203. Then paste into a Python REPL:
  204. ```python
  205. from orionbelt.parser import ReferenceResolver, TrackedLoader
  206. from orionbelt.compiler.pipeline import CompilationPipeline
  207. from orionbelt.models.query import QueryObject, QuerySelect
  208. model_yaml = """
  209. version: 1.0
  210. dataObjects:
  211. Orders:
  212. code: ORDERS
  213. columns:
  214. Price: { code: PRICE, abstractType: float }
  215. Country: { code: COUNTRY, abstractType: string }
  216. dimensions:
  217. Country:
  218. dataObject: Orders
  219. column: Country
  220. resultType: string
  221. measures:
  222. Total Revenue:
  223. resultType: float
  224. aggregation: sum
  225. expression: "{[Orders].[Price]}"
  226. """
  227. loader = TrackedLoader()
  228. raw, source_map = loader.load_string(model_yaml)
  229. resolver = ReferenceResolver()
  230. model, result = resolver.resolve(raw, source_map)
  231. query = QueryObject(select=QuerySelect(dimensions=["Country"], measures=["Total Revenue"]))
  232. pipeline = CompilationPipeline()
  233. output = pipeline.compile(query, model, "postgres")
  234. print(output.sql)
  235. ```
  236. Output:
  237. ```sql
  238. SELECT
  239. "Orders"."COUNTRY" AS "Country",
  240. CAST(SUM("Orders"."PRICE") AS NUMERIC(18, 2)) AS "Total Revenue"
  241. FROM ORDERS AS "Orders"
  242. GROUP BY "Orders"."COUNTRY"
  243. ```
  244. No env file needed — the compilation pipeline is stateless.
  245. **Start the servers:**
  246. ```bash
  247. orionbelt-api # REST API on :8000 (Swagger UI at /docs, Gradio UI at /ui)
  248. orionbelt-ui # standalone Gradio UI on :7860 (connects to API on :8000)
  249. FLIGHT_ENABLED=true orionbelt-api # API + Arrow Flight SQL on :8815 (DBeaver, Tableau, Power BI)
  250. PGWIRE_ENABLED=true orionbelt-api # API + PostgreSQL wire on :5432 (Tableau, DBeaver, Superset, psql, Dremio source)
  251. ```
  252. ### Option C2: Install with uv
  253. ```bash
  254. uv pip install orionbelt-semantic-layer
  255. ```
  256. ```bash
  257. uv run orionbelt-api # REST API on :8000 (Swagger UI at /docs, Gradio UI at /ui)
  258. uv run orionbelt-ui # standalone Gradio UI on :7860 (connects to API on :8000)
  259. FLIGHT_ENABLED=true uv run orionbelt-api # API + Arrow Flight SQL on :8815 (DBeaver, Tableau, Power BI)
  260. PGWIRE_ENABLED=true uv run orionbelt-api # API + PostgreSQL wire on :5432 (Tableau, DBeaver, Superset, psql, Dremio source)
  261. ```
  262. **Use the `obsl` CLI** (no server needed - compiles in-process):
  263. ```bash
  264. obsl validate model.yaml # lint a model (exit 1 on error, CI-friendly)
  265. obsl compile model.yaml -q query.json -d snowflake # print the generated SQL
  266. obsl compile model.yaml --sql 'SELECT "Region", "Sales" FROM model' # ... or from an OBSQL string
  267. obsl describe model.yaml # overview of data objects + artefacts
  268. obsl diagram model.yaml # Mermaid ER diagram
  269. obsl convert obml-to-osi model.yaml # OBML -> OSI (and osi-to-obml)
  270. obsl execute -q query.json --server http://host # run against a deployed model (omit MODEL)
  271. ```
  272. See the [CLI guide](https://ralforion.com/orionbelt-semantic-layer/guide/cli/) for all commands.
  273. **Smoke-test the Flight SQL surface** without a BI tool:
  274. ```bash
  275. uv run python examples/obsql.py 'SELECT version()'
  276. uv run python examples/obsql.py 'SHOW TABLES'
  277. uv run python examples/obsql.py 'SELECT "Region", "Total Sales" FROM sales LIMIT 5'
  278. # Multi-model deployment? Pick the model with -m:
  279. uv run python examples/obsql.py -m sales 'SHOW TABLES'
  280. uv run python examples/obsql.py --list # discover loaded models via REST
  281. ```
  282. ### Try OBSQL in 30 seconds
  283. **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+):
  284. ```bash
  285. PGWIRE_ENABLED=true uv run orionbelt-api &
  286. # Every BI tool already ships a Postgres ODBC/JDBC driver — point yours at :5432
  287. psql "host=localhost port=5432 user=obsl dbname=sales sslmode=disable" \
  288. -c 'SELECT "Region", "Total Sales" LIMIT 5'
  289. # All three measure forms compile to the same vendor SQL:
  290. psql "..." -c 'SELECT "Region", "Total Sales" FROM sales LIMIT 5' -- bare
  291. psql "..." -c 'SELECT "Region", MEASURE("Total Sales") FROM sales LIMIT 5' -- explicit marker
  292. psql "..." -c 'SELECT "Region", SUM("Total Sales") FROM sales LIMIT 5' -- matching aggregate
  293. ```
  294. See the [OBSQL reference](https://ralforion.com/orionbelt-semantic-layer/guide/semantic-ql/) for the full grammar.
  295. ### Option D: Docker
  296. **Stage 1 — Zero-config start** (models loaded later via API or UI):
  297. ```bash
  298. docker run -p 8080:8080 ralforion/orionbelt-semantic-layer-api
  299. ```
  300. Open [http://localhost:8080/docs](http://localhost:8080/docs) to explore the API.
  301. **Stage 2 — Realistic setup** with docker compose:
  302. ```yaml
  303. # docker-compose.yml
  304. services:
  305. api:
  306. image: ralforion/orionbelt-semantic-layer-api:3.1.0
  307. ports: ["8080:8080"]
  308. env_file: .env
  309. volumes:
  310. - ./models:/app/models:ro
  311. environment:
  312. MODEL_FILES: /app/models/my-model.obml.yml
  313. ui:
  314. image: ralforion/orionbelt-semantic-layer-ui:3.1.0
  315. ports: ["7860:7860"]
  316. environment:
  317. API_BASE_URL: http://api:8080
  318. ```
  319. ```bash
  320. docker compose up -d
  321. ```
  322. See [`.env.template`](.env.template) for the full environment variable reference.
  323. > **Docker notes:**
  324. > - `API_SERVER_HOST` is already `0.0.0.0` inside the container — no override needed.
  325. > - MCP via stdio does not work in Docker. Use the [MCP HTTP client](https://github.com/ralforion/orionbelt-semantic-layer-mcp) for containerized deployments.
  326. > - Mount models to `/app/models` (or any path) and set `MODEL_FILES` (comma-separated paths) to pre-load on startup.
  327. > - For production, pin a version tag (`:3.1.0`) rather than `:latest`.
  328. ### Claude Desktop / MCP
  329. The MCP server is a separate thin client that delegates to the REST API:
  330. **[orionbelt-semantic-layer-mcp](https://github.com/ralforion/orionbelt-semantic-layer-mcp)**
  331. Add to your Claude Desktop `claude_desktop_config.json`:
  332. ```json
  333. {
  334. "mcpServers": {
  335. "orionbelt": {
  336. "command": "uvx",
  337. "args": ["orionbelt-semantic-layer-mcp"]
  338. }
  339. }
  340. }
  341. ```
  342. Also works with Copilot, Cursor, and Windsurf. See the [MCP repo](https://github.com/ralforion/orionbelt-semantic-layer-mcp) for full setup options.
  343. ---
  344. ## Why OrionBelt?
  345. | | OrionBelt | dbt Semantic Layer | Cube | Malloy |
  346. |---|---|---|---|---|
  347. | **Model format** | YAML (OBML) | YAML on dbt models | YAML or JavaScript | Malloy language |
  348. | **Runtime** | Self-hosted service | dbt Cloud | Cube Core (self-hosted) or Cube Cloud | Library, plus the Publisher server |
  349. | **License** | BUSL-1.1 (converts to Apache 2.0) | Definitions open source; runtime in dbt Cloud | Apache 2.0 core + Cube Cloud | Open source |
  350. | **Query surfaces** | OBSQL over PostgreSQL wire and Arrow Flight SQL, REST, MCP, DB-API drivers, CLI | GraphQL, JDBC (Cloud) | SQL API (PostgreSQL wire), REST, GraphQL | Malloy language; Publisher REST and MCP |
  351. | **Multi-fact queries** | `UNION ALL` legs (CFL), fan-trap paths refused | `FULL OUTER JOIN` on shared entities | Per-fact subqueries joined on shared dimensions | Single-rooted sources |
  352. | **Same answer on every engine** | Pinned and executed (`x/0`, rounding, NULLs, JSON) | Inherits engine semantics | Inherits engine semantics | Partly normalized: `greatest` / `least` NULL if any argument is, `round` half away from zero, `length` in characters; `x / 0` is left to the engine (`inf` on DuckDB), and "perfect compatibility across all dialects for all functions is not guaranteed" |
  353. | **Lineage** | Per artefact and per query, down to columns and the joins chosen | Catalog DAG of semantic models and metrics; no per-query lineage | Cube Cloud Metadata API: lineage from cubes and members to source tables, with database names and SQL expressions, for catalog integrations; no per-query lineage | None documented |
  354. | **Interchange** | Apache Ossie both ways; the model as RDF with SPARQL | No | Apache Ossie import and export through the Cube CLI and Platform API (Oct 2026; the CLI is in preview, access via Cube support) | No |
  355. | **Business meaning in the model** | Rules compiled to the query that reports their findings; SKOS links to an external ontology | Column-level data tests; free-form `meta` | Free-form `meta` (`ai_context`) | Annotations, uninterpreted |
  356. Full, two-sided comparisons, including where each of these tools is ahead: [dbt](https://ralforion.com/orionbelt-semantic-layer/comparison/dbt/), [Cube](https://ralforion.com/orionbelt-semantic-layer/comparison/cube/), [Malloy](https://ralforion.com/orionbelt-semantic-layer/comparison/malloy/), [LookML](https://ralforion.com/orionbelt-semantic-layer/comparison/lookml/), [AtScale](https://ralforion.com/orionbelt-semantic-layer/comparison/atscale/).
  357. ---
  358. ## Features
  359. ### Semantic Modeling
  360. - **OBML Format** — YAML-based semantic models with data objects, dimensions, measures, metrics, and joins
  361. - **Cross-Schema Queries** — model data objects across multiple databases and schemas in a single model
  362. - **Static Model Filters** — mandatory WHERE conditions baked into the model, auto-applied with join extension
  363. - **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
  364. - **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
  365. - **OSI Interoperability** — bidirectional conversion between OBML and the Open Semantic Interchange format, now developed as [Apache Ossie (incubating)](https://github.com/apache/ossie)
  366. ### SQL Compilation
  367. - **8 SQL Dialects** — BigQuery, ClickHouse, Databricks, Dremio, DuckDB/MotherDuck, MySQL, Postgres, Snowflake
  368. - **Files and lakehouse tables** (v3.1.0+): Parquet, CSV and JSON files on disk or in object storage, and Apache Iceberg tables behind a REST catalog, read in place by a DuckDB data source
  369. - **AST-Based Generation** — custom SQL AST ensures correct, injection-safe SQL (not string templates)
  370. - **Star Schema & CFL** — automatic join resolution with Composite Fact Layer for multi-fact queries
  371. - **Data Types & Precision** — automatic CAST wrapping with dialect-specific type rendering and precision clamping
  372. - **Display Formatting** — number format patterns (`#,##0.00`, `0.00%`) on measures/metrics with locale-aware rendering
  373. - **Timezone Settings** — auto-detect database session timezone with `defaultTimezone` fallback and ISO 8601 serialization
  374. - **sqlglot Validation** — post-generation syntax check across all supported dialects
  375. ### Integration Surface
  376. - **REST API** — FastAPI endpoints for model management, validation, compilation, and execution
  377. - **MCP Server** — [separate thin client](https://github.com/ralforion/orionbelt-semantic-layer-mcp) for Claude, Copilot, Cursor, Windsurf
  378. - **AI Integrations** — LangChain, OpenAI Agents SDK, CrewAI, Google ADK, Vercel AI SDK, n8n, ChatGPT
  379. - **Gradio UI** — interactive web interface for model editing, query testing, and ER diagrams
  380. - **DB-API 2.0 + Flight SQL** — PEP 249 drivers and Arrow Flight SQL server for DBeaver, Tableau, Power BI; ships with `examples/obsql.py`, a tiny terminal CLI for testing the Flight surface without a BI tool
  381. - **DuckDB as a client** (v2.27.1+) - a plain DuckDB shell queries the layer, over either surface. `ATTACH ... (TYPE postgres)` mounts the model as a table (`SELECT ... FROM obsl.sales.model`, one `SET pg_use_text_protocol = true` first); the `adbc_scanner` community extension does it over Flight SQL with Arrow the whole way. Governed measures join to local tables and land in `CREATE TABLE AS`. [Guide](https://ralforion.com/orionbelt-semantic-layer/guide/duckdb/)
  382. - **PostgreSQL Wire Protocol** (v2.5.0+) — native Postgres-protocol surface on `:5432`. Every BI tool already ships a Postgres ODBC/JDBC driver, so the user side is "point your existing connection at OBSL and go" — Tableau, DBeaver, Superset, Power BI, plain `psql`, and **Dremio as a federated Postgres source** (Dremio → OBSL → optionally back to Dremio's lakehouse, full circle)
  383. ### Agent-Facing API
  384. - **One-shot Model + Queries**: submit task-specific OBML and independent sub-questions to `POST /v1/oneshot/batch`; get per-query results and optionally retain the model for follow-ups. See [Agent Workflows](https://ralforion.com/orionbelt-semantic-layer/guide/agent-workflows/).
  385. - **Model Health on Load** — every model load returns a `health` block with orphan dataObjects, fan-trap risks, and unreachable dimensions — agents skip the defensive second round trip
  386. - **Query Plan Endpoint** — `POST /query/plan` returns the planner's understanding (planner choice, physical tables, join path, `would_compile`) without compiling SQL or executing; opt-in `include_database_explain` adds the warehouse's raw EXPLAIN
  387. - **Structured Warnings** — every `warnings` list across the API uses a stable `{code, severity, message, path, hint, context}` shape with a documented code taxonomy; agents branch on codes instead of parsing messages
  388. - **Fuzzy `/find` Recovery** — when a search produces no exact or synonym hits, deterministic Levenshtein + trigram fallback returns near-miss candidates with scores and reasons
  389. - **Dimension-Value Search**: `POST /v1/values` lists or searches the values a dimension holds (exact, prefix, contains, then fuzzy), so an agent grounds a filter value in the data instead of guessing; the model's static filters apply, and `valueSearch: false` keeps a column's values private
  390. - **Model Examples** — optional OBML `examples:` block of canonical queries; `GET /examples` (with `?intent=` filtering) gives agents one-round-trip discovery of what a model is designed to answer
  391. ### Freshness-Driven Result Cache
  392. - **Source-level freshness contracts** — declare `refresh:` blocks on `dataObject` entries (interval / heartbeat / static); the cache derives query TTLs from the contracts of the physical tables a query touched, not from caller guesses
  393. - **Heartbeat invalidation** — one `POST /v1/heartbeat` to a physical table invalidates every cached query that depends on it, across every dataObject and session
  394. - **DuckDB metadata + Parquet results** — file-backed cache with type-precise serialization, lazy expiration, LRU capacity sweep; opt-in via `CACHE_BACKEND=file`
  395. - **Inverts the Cube/dbt/Looker pattern** — contracts live on the source, not the semantic abstraction; one source of truth across every cube/explore/saved query reading the table
  396. ### Developer Experience
  397. - **Source-Position Errors** — validation errors report exact YAML line and column
  398. - **ER Diagrams** — interactive Mermaid diagrams with zoom and download (MD/PNG/Turtle)
  399. - **Session Management** — TTL-scoped sessions with thread-safe model isolation
  400. - **JSON Schema** — full OBML and query schema for IDE autocompletion (`yaml-language-server`)
  401. ---
  402. ## Example
  403. ### Define a Semantic Model (OBML)
  404. ```yaml
  405. # yaml-language-server: $schema=https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer/main/schema/obml-schema.json
  406. version: 1.0
  407. dataObjects:
  408. Customers:
  409. code: CUSTOMERS
  410. database: WAREHOUSE
  411. schema: PUBLIC
  412. columns:
  413. Customer ID: { code: CUSTOMER_ID, abstractType: string }
  414. Country: { code: COUNTRY, abstractType: string }
  415. Orders:
  416. code: ORDERS
  417. database: WAREHOUSE
  418. schema: PUBLIC
  419. columns:
  420. Order Customer ID: { code: CUSTOMER_ID, abstractType: string }
  421. Price: { code: PRICE, abstractType: float }
  422. Quantity: { code: QUANTITY, abstractType: int }
  423. joins:
  424. - joinType: many-to-one
  425. joinTo: Customers
  426. columnsFrom: [Order Customer ID]
  427. columnsTo: [Customer ID]
  428. dimensions:
  429. Country:
  430. dataObject: Customers
  431. column: Country
  432. resultType: string
  433. measures:
  434. Revenue:
  435. resultType: float
  436. aggregation: sum
  437. expression: "{[Orders].[Price]} * {[Orders].[Quantity]}"
  438. dataType: "decimal(18, 2)"
  439. ```
  440. ### Compile via REST API
  441. ```bash
  442. # Create a session
  443. curl -s -X POST http://localhost:8080/v1/sessions | jq .session_id
  444. # -> "a1b2c3d4"
  445. # Load the model
  446. curl -s -X POST http://localhost:8080/v1/sessions/a1b2c3d4/models \
  447. -H "Content-Type: application/json" \
  448. -d '{"model_yaml": "..."}' | jq .model_id
  449. # -> "abcd1234"
  450. # Compile a query
  451. curl -s -X POST http://localhost:8080/v1/sessions/a1b2c3d4/query/sql \
  452. -H "Content-Type: application/json" \
  453. -d '{"model_id":"abcd1234","query":{"select":{"dimensions":["Country"],"measures":["Revenue"]}},"dialect":"postgres"}' \
  454. | jq -r .sql
  455. ```
  456. <details>
  457. <summary><strong>Generated SQL (Postgres)</strong></summary>
  458. ```sql
  459. SELECT
  460. "Customers"."COUNTRY" AS "Country",
  461. CAST(SUM("Orders"."PRICE" * "Orders"."QUANTITY") AS NUMERIC(18, 2)) AS "Revenue"
  462. FROM WAREHOUSE.PUBLIC.ORDERS AS "Orders"
  463. LEFT JOIN WAREHOUSE.PUBLIC.CUSTOMERS AS "Customers"
  464. ON "Orders"."CUSTOMER_ID" = "Customers"."CUSTOMER_ID"
  465. GROUP BY "Customers"."COUNTRY"
  466. ```
  467. </details>
  468. Change `dialect` to `bigquery`, `clickhouse`, `databricks`, `dremio`, `duckdb`, `mysql`, or `snowflake` for dialect-specific SQL.
  469. ---
  470. ## Gradio UI
  471. <p align="center">
  472. <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer/main/docs/assets/ui-sqlcompiler-dark.png" alt="OrionBelt Gradio UI showing side-by-side OBML model editor and compiled SQL output" width="900">
  473. </p>
  474. - **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
  475. - **Query Execution** — execute compiled queries against a connected database, view results with locale-aware number formatting, response metadata panel, TSV download and clipboard copy (requires `QUERY_EXECUTE=true`)
  476. - **ER Diagram** — interactive Mermaid ER diagram with zoom, column toggle, and download (MD/PNG/Turtle)
  477. - **Ontology Graph** — interactive vis-network visualization of the OBML graph (data objects, dimensions, measures, metrics, joins) with toggleable layers and adjustable node spacing
  478. - **Business Rules**: the model's rules with statistics; click a row to select one, show its OBML definition, test it or test all rules into a report
  479. - **SPARQL**: read-only SELECT / ASK over the model's OBSL graph, in an editor with SPARQL syntax highlighting and a gallery of ready-to-run examples
  480. - **Editor Toolbar** — clear, undo, redo, upload, download, and copy buttons on all code editors
  481. - **OSI Import/Export** — convert between OBML and OSI formats
  482. - **Dark/Light Mode** — toggle via header button, state persisted across sessions
  483. <p align="center">
  484. <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer/main/docs/assets/ui-business-rules-dark.png" alt="OrionBelt Business Rules tab listing the model's rules with statistics, a selected rule's OBML definition, and the report from testing all rules" width="900">
  485. </p>
  486. <p align="center">
  487. <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer/main/docs/assets/ui-ontology-graph-dark.png" alt="OrionBelt Ontology Graph tab showing the semantic model as an interactive network of data objects, dimensions, measures, metrics, and join relationships" width="900">
  488. </p>
  489. **Embedded mode** — the UI is mounted at `/ui` on the API server:
  490. ```bash
  491. pip install orionbelt-semantic-layer && orionbelt-api
  492. # -> UI at http://localhost:8000/ui
  493. ```
  494. **Standalone mode** — run API and UI as separate processes:
  495. ```bash
  496. orionbelt-api # API on :8000
  497. orionbelt-ui # UI on :7860 (connects to API on :8000)
  498. API_BASE_URL=http://remote-api:8080 orionbelt-ui # point UI to a remote API
  499. ```
  500. ---
  501. ## Documentation
  502. | Topic | Link |
  503. |-------|------|
  504. | Full docs site | [ralforion.com/orionbelt-semantic-layer](https://ralforion.com/orionbelt-semantic-layer/) |
  505. | Installation | [getting-started/installation](https://ralforion.com/orionbelt-semantic-layer/getting-started/installation/) |
  506. | Quick Start | [getting-started/quickstart](https://ralforion.com/orionbelt-semantic-layer/getting-started/quickstart/) |
  507. | Docker & Deployment | [getting-started/docker](https://ralforion.com/orionbelt-semantic-layer/getting-started/docker/) |
  508. | Development | [getting-started/development](https://ralforion.com/orionbelt-semantic-layer/getting-started/development/) |
  509. | OBML Model Format | [guide/model-format](https://ralforion.com/orionbelt-semantic-layer/guide/model-format/) |
  510. | Query Language | [guide/query-language](https://ralforion.com/orionbelt-semantic-layer/guide/query-language/) |
  511. | SQL Dialects | [guide/dialects](https://ralforion.com/orionbelt-semantic-layer/guide/dialects/) |
  512. | Period-over-Period Metrics | [guide/period-over-period](https://ralforion.com/orionbelt-semantic-layer/guide/period-over-period/) |
  513. | Trend Analysis (rank / lag / lead / ntile, partitioned MAs, statistical aggregates) | [guide/trend-analysis](https://ralforion.com/orionbelt-semantic-layer/guide/trend-analysis/) |
  514. | Compilation Pipeline | [guide/compilation](https://ralforion.com/orionbelt-semantic-layer/guide/compilation/) |
  515. | OBSL Graph & SPARQL | [guide/obsl](https://ralforion.com/orionbelt-semantic-layer/guide/obsl/) |
  516. | Business Rules | [guide/business-rules](https://ralforion.com/orionbelt-semantic-layer/guide/business-rules/) |
  517. | External Concept Mappings | [guide/concept-mappings](https://ralforion.com/orionbelt-semantic-layer/guide/concept-mappings/) |
  518. | Gradio UI | [guide/ui](https://ralforion.com/orionbelt-semantic-layer/guide/ui/) |
  519. | AI Integrations | [guide/integrations](https://ralforion.com/orionbelt-semantic-layer/guide/integrations/) |
  520. | OSI Interoperability | [guide/osi](https://ralforion.com/orionbelt-semantic-layer/guide/osi/) |
  521. | REST API Endpoints | [api/endpoints](https://ralforion.com/orionbelt-semantic-layer/api/endpoints/) |
  522. | DB-API Drivers & Flight SQL | [drivers](https://ralforion.com/orionbelt-semantic-layer/drivers/) |
  523. | Architecture | [reference/architecture](https://ralforion.com/orionbelt-semantic-layer/reference/architecture/) |
  524. | Configuration | [reference/configuration](https://ralforion.com/orionbelt-semantic-layer/reference/configuration/) |
  525. | Sales Model Walkthrough | [examples/sales-model](https://ralforion.com/orionbelt-semantic-layer/examples/sales-model/) |
  526. | Multi-Dialect Output | [examples/multi-dialect](https://ralforion.com/orionbelt-semantic-layer/examples/multi-dialect/) |
  527. | Multi-Fact: Sales & Returns | [examples/multi-fact](https://ralforion.com/orionbelt-semantic-layer/examples/multi-fact/) |
  528. | TPC-DS Benchmark | [examples/tpcds](https://ralforion.com/orionbelt-semantic-layer/examples/tpcds/) |
  529. | Quickstart Notebook | [examples/quickstart.ipynb](examples/quickstart.ipynb) |
  530. | **Comparison: Overview** | [comparison/](https://ralforion.com/orionbelt-semantic-layer/comparison/) |
  531. | Comparison: vs. dbt Semantic Layer | [comparison/dbt](https://ralforion.com/orionbelt-semantic-layer/comparison/dbt/) |
  532. | Comparison: vs. Malloy | [comparison/malloy](https://ralforion.com/orionbelt-semantic-layer/comparison/malloy/) |
  533. | Comparison: vs. LookML / Looker | [comparison/lookml](https://ralforion.com/orionbelt-semantic-layer/comparison/lookml/) |
  534. | Comparison: vs. Cube | [comparison/cube](https://ralforion.com/orionbelt-semantic-layer/comparison/cube/) |
  535. | Comparison: vs. AtScale | [comparison/atscale](https://ralforion.com/orionbelt-semantic-layer/comparison/atscale/) |
  536. ---
  537. ## Status & Roadmap
  538. | Status | Area |
  539. |--------|------|
  540. | Shipped | 8 SQL dialects, REST API, MCP server, Gradio UI, DB-API drivers, Flight SQL, **PostgreSQL wire protocol (v2.5.0+)**: Tableau / DBeaver / Superset / Power BI / `psql` / **Dremio as a federated Postgres source**, OBSL/SPARQL, **Apache Ossie (OSI) 0.3 interop** with bidirectional schema validation, AI integrations (LangChain, CrewAI, ADK, etc.), model inheritance & extends, data types & numerical precision, timezone settings, grain & filter context overrides, **Trend Analysis**: partitioned rolling windows, `MetricType.WINDOW` for rank/lag/lead/ntile, 9 statistical aggregates (CORR, COVAR_*, REGR_*, STDDEV_*, VAR_*), **Unified authentication (v2.12.0)** across REST / Flight / pgwire / UI: `AUTH_MODE=api_key` with shared key store, pgwire SCRAM-SHA-256 + cleartext, **Artefacts Composability Resolution (ACR, v2.14.0)**: a `composables` endpoint that, given the query so far, returns which dimensions / measures / metrics can still be added (including CFL candidates), powering guided query building, **[`obsl` CLI](https://ralforion.com/orionbelt-semantic-layer/guide/cli/) (v2.17.0+)** for automation & CI/CD: `validate`, `compile`, `execute`, `describe`, `lineage`, `convert`, `rules` and more, in-process or against a server with `--server`, **[Federated queries](https://ralforion.com/orionbelt-semantic-layer/guide/federation/) (v3.0.0+)**: a model's data objects can live in different databases. A query reading more than one is split into one query per data source, run at once, and combined in an in-memory DuckDB, **[Files and lakehouse tables](https://ralforion.com/orionbelt-semantic-layer/guide/files-and-lakehouse/) (v3.1.0+)**: Parquet, CSV, JSON and Apache Iceberg read in place by a DuckDB data source |
  541. | Planned | OIDC / SSO authentication & per-token authorization scopes, DDL view generation (CREATE VIEW from queries), additional dialects, additional BI tool integrations, pre-aggregation / materialization layer |
  542. ---
  543. ## Commercial Offerings
  544. OrionBelt Semantic Layer is source-available under BUSL-1.1 until its Apache-2.0 conversion — the free distribution has full parity on the shipped v2.6 surface and is production-grade for self-hosted use. For teams that want production support, a managed runtime, or embedded analytics terms, RALFORION offers:
  545. - **Embedded analytics license** — relicensing terms for shipping OBSL inside a commercial product
  546. - **Commercial cloud offering** — managed OrionBelt runtime with SLAs
  547. - **Enterprise features** — capabilities tailored for enterprise deployments
  548. - **Consulting + support** — implementation, modeling, and production support
  549. Contact [RALFORION d.o.o.](https://ralforion.com) for details.
  550. ---
  551. ## Companion Project
  552. ### [OrionBelt Analytics](https://github.com/ralforion/orionbelt-analytics)
  553. 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.
  554. <p align="center">
  555. <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer/main/docs/assets/architecture.png" alt="Architecture diagram showing OrionBelt Analytics generating ontologies from database schemas, feeding into OrionBelt Semantic Layer for SQL compilation" width="800">
  556. </p>
  557. ---
  558. ## Development
  559. Contributing to OrionBelt or running from source:
  560. ```bash
  561. git clone https://github.com/ralforion/orionbelt-semantic-layer.git
  562. cd orionbelt-semantic-layer
  563. uv sync # install all deps (dev, docs, ui, flight, drivers)
  564. uv run orionbelt-api # start API on :8000
  565. ```
  566. ```bash
  567. # Quality
  568. uv run pytest # run tests
  569. uv run ruff check src/ # lint
  570. uv run ruff format src/ tests/ # format
  571. uv run mypy src/ # type check
  572. # Docs
  573. uv sync --extra docs && uv run mkdocs serve # docs on :8080
  574. # CI workflows
  575. ./scripts/check-action-pins.sh # verify every Action pin
  576. ./scripts/check-action-pins.sh --offline # skip the upstream tag lookups
  577. ```
  578. ### GitHub Actions pinning
  579. Every `uses:` in `.github/workflows` is pinned to a 40-character commit SHA
  580. rather than a tag, because a tag such as `v7` is a movable label: it runs
  581. whichever commit its owner has pointed it at when the job starts. The
  582. `# vX.Y.Z` comment beside each SHA names the exact patch release that SHA was
  583. cut from, and it has to be a patch release, since a major tag moves with every
  584. upstream bump.
  585. Pinning fixes *which* code runs but makes the reference unreadable, so
  586. `scripts/check-action-pins.sh` keeps the SHA and its comment honest. It walks
  587. every `uses:` line and requires a commit SHA, an owner from its `ALLOWED_OWNERS`
  588. allowlist, and an exact-patch version comment, then resolves that tag upstream
  589. with `git ls-remote` and fails when the commit it names is not the one pinned.
  590. Container actions must be pinned by digest; local `./` actions are skipped.
  591. `--offline` checks only the SHA and comment format, with no network calls.
  592. The check runs as the `pins` job in CI, and as the first step after checkout in
  593. the workflows that publish (Docker, PyPI, docs), so a tag can never ship
  594. artifacts built by steps whose pins were never verified. Adding an owner to
  595. `ALLOWED_OWNERS` is a deliberate decision: a SHA matching its own tag says
  596. nothing about whether that action belongs in this repo at all.
  597. ---
  598. ## License
  599. Copyright © 2026 [RALFORION d.o.o.](https://ralforion.com)
  600. OrionBelt® is a registered trademark of RALFORION d.o.o.
  601. Licensed under the [Business Source License 1.1](LICENSE) (SPDX: `BUSL-1.1`). The Licensed Work will convert to Apache License 2.0 on 2030-03-16.
  602. Third-party works redistributed by OrionBelt, and their terms, are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
  603. By contributing to this project, you agree to the [Contributor License Agreement](CLA.md).
  604. For commercial licensing inquiries, contact: licensing@ralforion.com
  605. ---
  606. <p align="center">
  607. <a href="https://ralforion.com">
  608. <img src="https://raw.githubusercontent.com/ralforion/orionbelt-semantic-layer/main/docs/assets/RALFORION_doo_Logo.png" alt="RALFORION d.o.o." width="200">
  609. </a>
  610. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.