{"id":45164333,"url":"https://github.com/ralfbecher/orionbelt-semantic-layer","last_synced_at":"2026-05-11T00:23:57.290Z","repository":{"id":338884124,"uuid":"1154643037","full_name":"ralfbecher/orionbelt-semantic-layer","owner":"ralfbecher","description":"API-first semantic engine and query planner for AI agents that compiles declarative YAML models into optimized, dialect-specific SQL across BigQuery, PostgreSQL, Snowflake, ClickHouse, Dremio, Databricks, DuckDB, and MySQL.","archived":false,"fork":false,"pushed_at":"2026-04-30T21:04:30.000Z","size":13947,"stargazers_count":41,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-30T22:13:34.810Z","etag":null,"topics":["agentic-ai","ai-analytics","ai-workflow","bigquery","business-intelligence","clickhouse","data-analytics","databricks","dremio","duckdb","mcp","mcp-server","model-context-protocol","mysql","postgresql","rest-api","semantic-layer","snowflake","yaml"],"latest_commit_sha":null,"homepage":"https://ralforion.com/orionbelt-semantic-layer/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ralfbecher.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG-versions.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"}},"created_at":"2026-02-10T16:10:48.000Z","updated_at":"2026-04-30T21:04:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"5f9b3db3-08de-467f-8556-8cbce4eaa374","html_url":"https://github.com/ralfbecher/orionbelt-semantic-layer","commit_stats":null,"previous_names":["ralfbecher/orionbelt-semantic-layer"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/ralfbecher/orionbelt-semantic-layer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralfbecher%2Forionbelt-semantic-layer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralfbecher%2Forionbelt-semantic-layer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralfbecher%2Forionbelt-semantic-layer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralfbecher%2Forionbelt-semantic-layer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ralfbecher","download_url":"https://codeload.github.com/ralfbecher/orionbelt-semantic-layer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralfbecher%2Forionbelt-semantic-layer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32590466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-analytics","ai-workflow","bigquery","business-intelligence","clickhouse","data-analytics","databricks","dremio","duckdb","mcp","mcp-server","model-context-protocol","mysql","postgresql","rest-api","semantic-layer","snowflake","yaml"],"created_at":"2026-02-20T06:30:47.689Z","updated_at":"2026-05-11T00:23:57.278Z","avatar_url":"https://github.com/ralfbecher.png","language":"Python","funding_links":[],"categories":["Semantic Layers \u0026 Metrics","Integrations"],"sub_categories":["Web Clients (WebAssembly)"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ralfbecher/orionbelt-semantic-layer/main/docs/assets/ORIONBELT_Logo.png\" alt=\"OrionBelt Semantic Layer logo — a stylized belt of three stars\" width=\"400\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eOrionBelt Semantic Layer\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eCompile and execute YAML semantic models as analytical SQL across multiple database dialects\u003c/strong\u003e\u003c/p\u003e\n\n\u003c!-- TODO: confirm PyPI publication — if not yet published, remove pypi badge --\u003e\n[![Live Demo](https://img.shields.io/badge/Live_Demo-Try_it_now-brightgreen?style=for-the-badge)](https://orionbelt.ralforion.com/ui/?__theme=dark)\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ralfbecher/orionbelt-semantic-layer/blob/main/examples/quickstart_colab.ipynb)\n\n[![GitHub stars](https://img.shields.io/github/stars/ralfbecher/orionbelt-semantic-layer?style=social)](https://github.com/ralfbecher/orionbelt-semantic-layer)\n[![Version 2.3.1](https://img.shields.io/badge/version-2.3.1-purple.svg)](https://github.com/ralfbecher/orionbelt-semantic-layer/releases)\n[![PyPI](https://img.shields.io/pypi/v/orionbelt-semantic-layer?logo=pypi\u0026logoColor=white)](https://pypi.org/project/orionbelt-semantic-layer/)\n[![Docker Hub](https://img.shields.io/docker/pulls/ralforion/orionbelt-api?logo=docker\u0026label=Docker%20Hub)](https://hub.docker.com/repositories/ralforion)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: BSL 1.1](https://img.shields.io/badge/License-BSL_1.1-orange.svg)](https://github.com/ralfbecher/orionbelt-semantic-layer/blob/main/LICENSE)\n\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.128+-009688.svg?logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com)\n[![Pydantic v2](https://img.shields.io/badge/Pydantic-v2-E92063.svg?logo=pydantic\u0026logoColor=white)](https://docs.pydantic.dev)\n[![Gradio](https://img.shields.io/badge/Gradio-5.0+-F97316.svg?logo=gradio\u0026logoColor=white)](https://www.gradio.app)\n\n[![BigQuery](https://img.shields.io/badge/BigQuery-669DF6.svg?logo=googlebigquery\u0026logoColor=white)](https://cloud.google.com/bigquery)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1.svg?logo=postgresql\u0026logoColor=white)](https://www.postgresql.org)\n[![Snowflake](https://img.shields.io/badge/Snowflake-29B5E8.svg?logo=snowflake\u0026logoColor=white)](https://www.snowflake.com)\n[![ClickHouse](https://img.shields.io/badge/ClickHouse-FFCC01.svg?logo=clickhouse\u0026logoColor=black)](https://clickhouse.com)\n[![Dremio](https://img.shields.io/badge/Dremio-31B48D.svg)](https://www.dremio.com)\n[![Databricks](https://img.shields.io/badge/Databricks-FF3621.svg?logo=databricks\u0026logoColor=white)](https://www.databricks.com)\n[![DuckDB](https://img.shields.io/badge/DuckDB-FFF000.svg?logo=duckdb\u0026logoColor=black)](https://duckdb.org)\n[![MySQL](https://img.shields.io/badge/MySQL-4479A1.svg?logo=mysql\u0026logoColor=white)](https://www.mysql.com)\n\nOrionBelt 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.\n\n**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.\n\n\u003e **Companion Project:** [OrionBelt Analytics](https://github.com/ralfbecher/orionbelt-analytics) — an ontology-based MCP server that analyzes database schemas and generates RDF/OWL ontologies. Together they let AI assistants navigate your data landscape through ontologies and compile safe, dialect-aware analytical SQL.\n\n## Table of Contents\n\n- [Try it in 30 Seconds](#try-it-in-30-seconds) — Live Demo | Colab | PyPI | uv | Docker\n- [Claude Desktop / MCP](#claude-desktop--mcp)\n- [Why OrionBelt?](#why-orionbelt)\n- [Features](#features)\n- [Example](#example)\n- [Gradio UI](#gradio-ui)\n- [Documentation](#documentation)\n- [Status \u0026 Roadmap](#status--roadmap)\n- [Companion Project](#companion-project)\n- [Development](#development)\n\n---\n\n## Try it in 30 Seconds\n\n### Option A: Live Demo (no install)\n\n**[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.\n\nAPI explorer: [Swagger UI](https://orionbelt.ralforion.com/docs) | [ReDoc](https://orionbelt.ralforion.com/redoc)\n\n### Option B: Google Colab (no install)\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ralfbecher/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.\n\n### Option C: Install from PyPI\n\n```bash\npip install orionbelt-semantic-layer\n```\n\nThen paste into a Python REPL:\n\n```python\nfrom orionbelt.parser import ReferenceResolver, TrackedLoader\nfrom orionbelt.compiler.pipeline import CompilationPipeline\nfrom orionbelt.models.query import QueryObject, QuerySelect\n\nmodel_yaml = \"\"\"\nversion: \"1.0\"\ndataObjects:\n  Orders:\n    code: ORDERS\n    columns:\n      Price: { code: PRICE, abstractType: float }\n      Country: { code: COUNTRY, abstractType: string }\ndimensions:\n  Country:\n    dataObject: Orders\n    column: Country\n    resultType: string\nmeasures:\n  Total Revenue:\n    resultType: float\n    aggregation: sum\n    expression: \"{[Orders].[Price]}\"\n\"\"\"\n\nloader = TrackedLoader()\nraw, source_map = loader.load_string(model_yaml)\nresolver = ReferenceResolver()\nmodel, result = resolver.resolve(raw, source_map)\n\nquery = QueryObject(select=QuerySelect(dimensions=[\"Country\"], measures=[\"Total Revenue\"]))\npipeline = CompilationPipeline()\noutput = pipeline.compile(query, model, \"postgres\")\nprint(output.sql)\n```\n\nOutput:\n\n```sql\nSELECT\n  \"Orders\".\"COUNTRY\" AS \"Country\",\n  CAST(SUM(\"Orders\".\"PRICE\") AS NUMERIC(18, 2)) AS \"Total Revenue\"\nFROM ORDERS AS \"Orders\"\nGROUP BY \"Orders\".\"COUNTRY\"\n```\n\nNo env file needed — the compilation pipeline is stateless.\n\n**Start the servers:**\n\n```bash\norionbelt-api                              # REST API on :8000 (Swagger UI at /docs, Gradio UI at /ui)\norionbelt-ui                               # standalone Gradio UI on :7860 (connects to API on :8000)\nFLIGHT_ENABLED=true orionbelt-api          # API + Arrow Flight SQL on :8815 (DBeaver, Tableau, Power BI)\n```\n\n### Option C2: Install with uv\n\n```bash\nuv pip install orionbelt-semantic-layer\n```\n\n```bash\nuv run orionbelt-api                       # REST API on :8000 (Swagger UI at /docs, Gradio UI at /ui)\nuv run orionbelt-ui                        # standalone Gradio UI on :7860 (connects to API on :8000)\nFLIGHT_ENABLED=true uv run orionbelt-api   # API + Arrow Flight SQL on :8815 (DBeaver, Tableau, Power BI)\n```\n\n### Option D: Docker\n\n**Stage 1 — Zero-config start** (models loaded later via API or UI):\n\n```bash\ndocker run -p 8080:8080 ralforion/orionbelt-api\n```\n\nOpen [http://localhost:8080/docs](http://localhost:8080/docs) to explore the API.\n\n**Stage 2 — Realistic setup** with docker compose:\n\n```yaml\n# docker-compose.yml\nservices:\n  api:\n    image: ralforion/orionbelt-api:2.3.1\n    ports: [\"8080:8080\"]\n    env_file: .env\n    volumes:\n      - ./models:/app/models:ro\n    environment:\n      MODEL_FILE: /app/models/my-model.obml.yml\n\n  ui:\n    image: ralforion/orionbelt-ui:2.3.1\n    ports: [\"7860:7860\"]\n    environment:\n      API_BASE_URL: http://api:8080\n```\n\n```bash\ndocker compose up -d\n```\n\nSee [`.env.template`](.env.template) for the full environment variable reference.\n\n\u003e **Docker notes:**\n\u003e - `API_SERVER_HOST` is already `0.0.0.0` inside the container — no override needed.\n\u003e - MCP via stdio does not work in Docker. Use the [MCP HTTP client](https://github.com/ralfbecher/orionbelt-semantic-layer-mcp) for containerized deployments.\n\u003e - Mount models to `/app/models` (or any path) and set `MODEL_FILE` to pre-load on startup.\n\u003e - For production, pin a version tag (`:2.3.1`) rather than `:latest`.\n\n### Claude Desktop / MCP\n\nThe MCP server is a separate thin client that delegates to the REST API:\n\n**[orionbelt-semantic-layer-mcp](https://github.com/ralfbecher/orionbelt-semantic-layer-mcp)**\n\nAdd to your Claude Desktop `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"orionbelt\": {\n      \"command\": \"uvx\",\n      \"args\": [\"orionbelt-semantic-layer-mcp\"]\n    }\n  }\n}\n```\n\nAlso works with Copilot, Cursor, and Windsurf. See the [MCP repo](https://github.com/ralfbecher/orionbelt-semantic-layer-mcp) for full setup options.\n\n---\n\n## Why OrionBelt?\n\n| | OrionBelt | dbt Semantic Layer | Cube | Malloy |\n|---|---|---|---|---|\n| **Model format** | YAML-only (OBML) | Python + YAML | JavaScript | Custom DSL |\n| **SQL generation** | AST-based (injection-safe) | String templates | String templates | Compiler |\n| **Multi-dialect** | 8 dialects, no runtime lock-in | dbt Cloud required | Cube Cloud or self-host | BigQuery-focused |\n| **Multi-fact queries** | Star Schema + CFL planner (fan-trap prevention) | Limited | Pre-aggregations | Automatic joins |\n| **Integration surface** | REST API + MCP + Gradio UI | dbt Cloud API | REST + GraphQL | VS Code extension |\n| **Deployment** | Self-host anywhere, single binary | SaaS (Cloud) | SaaS or self-host | Library |\n| **License** | BSL 1.1 (converts to Apache 2.0) | Apache 2.0 | AGPL / proprietary | MIT |\n\n---\n\n## Features\n\n### Semantic Modeling\n\n- **OBML Format** — YAML-based semantic models with data objects, dimensions, measures, metrics, and joins\n- **Cross-Schema Queries** — model data objects across multiple databases and schemas in a single model\n- **Static Model Filters** — mandatory WHERE conditions baked into the model, auto-applied with join extension\n- **OBSL Graph \u0026 SPARQL** — RDF graph export and read-only SPARQL querying for every loaded model\n- **OSI Interoperability** — bidirectional conversion between OBML and Open Semantic Interchange format\n\n### SQL Compilation\n\n- **8 SQL Dialects** — BigQuery, ClickHouse, Databricks, Dremio, DuckDB/MotherDuck, MySQL, Postgres, Snowflake\n- **AST-Based Generation** — custom SQL AST ensures correct, injection-safe SQL (not string templates)\n- **Star Schema \u0026 CFL** — automatic join resolution with Composite Fact Layer for multi-fact queries\n- **Data Types \u0026 Precision** — automatic CAST wrapping with dialect-specific type rendering and precision clamping\n- **Display Formatting** — number format patterns (`#,##0.00`, `0.00%`) on measures/metrics with locale-aware rendering\n- **Timezone Settings** — auto-detect database session timezone with `defaultTimezone` fallback and ISO 8601 serialization\n- **sqlglot Validation** — post-generation syntax check across all supported dialects\n\n### Integration Surface\n\n- **REST API** — FastAPI endpoints for model management, validation, compilation, and execution\n- **MCP Server** — [separate thin client](https://github.com/ralfbecher/orionbelt-semantic-layer-mcp) for Claude, Copilot, Cursor, Windsurf\n- **AI Integrations** — LangChain, OpenAI Agents SDK, CrewAI, Google ADK, Vercel AI SDK, n8n, ChatGPT\n- **Gradio UI** — interactive web interface for model editing, query testing, and ER diagrams\n- **DB-API 2.0 + Flight SQL** — PEP 249 drivers and Arrow Flight SQL server for DBeaver, Tableau, Power BI\n\n### Agent-Facing API\n\n- **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\n- **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\n- **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\n- **Fuzzy `/find` Recovery** — when a search produces no exact or synonym hits, deterministic Levenshtein + trigram fallback returns near-miss candidates with scores and reasons\n- **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\n\n### Freshness-Driven Result Cache\n\n- **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\n- **Heartbeat invalidation** — one `POST /v1/heartbeat` to a physical table invalidates every cached query that depends on it, across every dataObject and session\n- **DuckDB metadata + Parquet results** — file-backed cache with type-precise serialization, lazy expiration, LRU capacity sweep; opt-in via `CACHE_BACKEND=file`\n- **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\n\n### Developer Experience\n\n- **Source-Position Errors** — validation errors report exact YAML line and column\n- **ER Diagrams** — interactive Mermaid diagrams with zoom and download (MD/PNG/Turtle)\n- **Session Management** — TTL-scoped sessions with thread-safe model isolation\n- **JSON Schema** — full OBML and query schema for IDE autocompletion (`yaml-language-server`)\n\n---\n\n## Example\n\n### Define a Semantic Model (OBML)\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/ralfbecher/orionbelt-semantic-layer/main/schema/obml-schema.json\nversion: \"1.0\"\ndataObjects:\n  Customers:\n    code: CUSTOMERS\n    database: WAREHOUSE\n    schema: PUBLIC\n    columns:\n      Customer ID: { code: CUSTOMER_ID, abstractType: string }\n      Country:     { code: COUNTRY, abstractType: string }\n\n  Orders:\n    code: ORDERS\n    database: WAREHOUSE\n    schema: PUBLIC\n    columns:\n      Order Customer ID: { code: CUSTOMER_ID, abstractType: string }\n      Price:             { code: PRICE, abstractType: float }\n      Quantity:          { code: QUANTITY, abstractType: int }\n    joins:\n      - joinType: many-to-one\n        joinTo: Customers\n        columnsFrom: [Order Customer ID]\n        columnsTo: [Customer ID]\n\ndimensions:\n  Country:\n    dataObject: Customers\n    column: Country\n    resultType: string\n\nmeasures:\n  Revenue:\n    resultType: float\n    aggregation: sum\n    expression: \"{[Orders].[Price]} * {[Orders].[Quantity]}\"\n    dataType: \"decimal(18, 2)\"\n```\n\n### Compile via REST API\n\n```bash\n# Create a session\ncurl -s -X POST http://localhost:8080/v1/sessions | jq .session_id\n# -\u003e \"a1b2c3d4\"\n\n# Load the model\ncurl -s -X POST http://localhost:8080/v1/sessions/a1b2c3d4/models \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model_yaml\": \"...\"}' | jq .model_id\n# -\u003e \"abcd1234\"\n\n# Compile a query\ncurl -s -X POST http://localhost:8080/v1/sessions/a1b2c3d4/query/sql \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model_id\":\"abcd1234\",\"query\":{\"select\":{\"dimensions\":[\"Country\"],\"measures\":[\"Revenue\"]}},\"dialect\":\"postgres\"}' \\\n  | jq -r .sql\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGenerated SQL (Postgres)\u003c/strong\u003e\u003c/summary\u003e\n\n```sql\nSELECT\n  \"Customers\".\"COUNTRY\" AS \"Country\",\n  CAST(SUM(\"Orders\".\"PRICE\" * \"Orders\".\"QUANTITY\") AS NUMERIC(18, 2)) AS \"Revenue\"\nFROM WAREHOUSE.PUBLIC.ORDERS AS \"Orders\"\nLEFT JOIN WAREHOUSE.PUBLIC.CUSTOMERS AS \"Customers\"\n  ON \"Orders\".\"CUSTOMER_ID\" = \"Customers\".\"CUSTOMER_ID\"\nGROUP BY \"Customers\".\"COUNTRY\"\n```\n\n\u003c/details\u003e\n\nChange `dialect` to `bigquery`, `clickhouse`, `databricks`, `dremio`, `duckdb`, `mysql`, or `snowflake` for dialect-specific SQL.\n\n---\n\n## Gradio UI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ralfbecher/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\"\u003e\n\u003c/p\u003e\n\n- **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\n- **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`)\n- **ER Diagram** — interactive Mermaid ER diagram with zoom, column toggle, and download (MD/PNG/Turtle)\n- **Ontology Graph** — interactive vis-network visualization of the OBML graph (data objects, dimensions, measures, metrics, joins) with toggleable layers and adjustable node spacing\n- **Editor Toolbar** — clear, undo, redo, upload, download, and copy buttons on all code editors\n- **OSI Import/Export** — convert between OBML and OSI formats\n- **Dark/Light Mode** — toggle via header button, state persisted across sessions\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ralfbecher/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\"\u003e\n\u003c/p\u003e\n\n**Embedded mode** — the UI is mounted at `/ui` on the API server:\n\n```bash\npip install orionbelt-semantic-layer \u0026\u0026 orionbelt-api\n# -\u003e UI at http://localhost:8000/ui\n```\n\n**Standalone mode** — run API and UI as separate processes:\n\n```bash\norionbelt-api                                              # API on :8000\norionbelt-ui                                               # UI on :7860 (connects to API on :8000)\nAPI_BASE_URL=http://remote-api:8080 orionbelt-ui           # point UI to a remote API\n```\n\n---\n\n## Documentation\n\n| Topic | Link |\n|-------|------|\n| Full docs site | [ralforion.com/orionbelt-semantic-layer](https://ralforion.com/orionbelt-semantic-layer/) |\n| Installation | [getting-started/installation](https://ralforion.com/orionbelt-semantic-layer/getting-started/installation/) |\n| Quick Start | [getting-started/quickstart](https://ralforion.com/orionbelt-semantic-layer/getting-started/quickstart/) |\n| Docker \u0026 Deployment | [getting-started/docker](https://ralforion.com/orionbelt-semantic-layer/getting-started/docker/) |\n| Development | [getting-started/development](https://ralforion.com/orionbelt-semantic-layer/getting-started/development/) |\n| OBML Model Format | [guide/model-format](https://ralforion.com/orionbelt-semantic-layer/guide/model-format/) |\n| Query Language | [guide/query-language](https://ralforion.com/orionbelt-semantic-layer/guide/query-language/) |\n| SQL Dialects | [guide/dialects](https://ralforion.com/orionbelt-semantic-layer/guide/dialects/) |\n| Period-over-Period Metrics | [guide/period-over-period](https://ralforion.com/orionbelt-semantic-layer/guide/period-over-period/) |\n| Compilation Pipeline | [guide/compilation](https://ralforion.com/orionbelt-semantic-layer/guide/compilation/) |\n| OBSL Graph \u0026 SPARQL | [guide/obsl](https://ralforion.com/orionbelt-semantic-layer/guide/obsl/) |\n| Gradio UI | [guide/ui](https://ralforion.com/orionbelt-semantic-layer/guide/ui/) |\n| AI Integrations | [guide/integrations](https://ralforion.com/orionbelt-semantic-layer/guide/integrations/) |\n| OSI Interoperability | [guide/osi](https://ralforion.com/orionbelt-semantic-layer/guide/osi/) |\n| REST API Endpoints | [api/endpoints](https://ralforion.com/orionbelt-semantic-layer/api/endpoints/) |\n| DB-API Drivers \u0026 Flight SQL | [drivers](https://ralforion.com/orionbelt-semantic-layer/drivers/) |\n| Architecture | [reference/architecture](https://ralforion.com/orionbelt-semantic-layer/reference/architecture/) |\n| Configuration | [reference/configuration](https://ralforion.com/orionbelt-semantic-layer/reference/configuration/) |\n| Sales Model Walkthrough | [examples/sales-model](https://ralforion.com/orionbelt-semantic-layer/examples/sales-model/) |\n| Multi-Dialect Output | [examples/multi-dialect](https://ralforion.com/orionbelt-semantic-layer/examples/multi-dialect/) |\n| Multi-Fact: Sales \u0026 Returns | [examples/multi-fact](https://ralforion.com/orionbelt-semantic-layer/examples/multi-fact/) |\n| TPC-DS Benchmark | [examples/tpcds](https://ralforion.com/orionbelt-semantic-layer/examples/tpcds/) |\n| Quickstart Notebook | [examples/quickstart.ipynb](examples/quickstart.ipynb) |\n| **Comparison: Overview** | [comparison/](https://ralforion.com/orionbelt-semantic-layer/comparison/) |\n| Comparison: vs. dbt Semantic Layer | [comparison/dbt](https://ralforion.com/orionbelt-semantic-layer/comparison/dbt/) |\n| Comparison: vs. Malloy | [comparison/malloy](https://ralforion.com/orionbelt-semantic-layer/comparison/malloy/) |\n| Comparison: vs. LookML / Looker | [comparison/lookml](https://ralforion.com/orionbelt-semantic-layer/comparison/lookml/) |\n| Comparison: vs. Cube | [comparison/cube](https://ralforion.com/orionbelt-semantic-layer/comparison/cube/) |\n| Comparison: vs. AtScale | [comparison/atscale](https://ralforion.com/orionbelt-semantic-layer/comparison/atscale/) |\n\n---\n\n## Status \u0026 Roadmap\n\n| Status | Area |\n|--------|------|\n| Shipped | 8 SQL dialects, REST API, MCP server, Gradio UI, DB-API drivers, Flight SQL, OBSL/SPARQL, OSI interop, AI integrations (LangChain, CrewAI, ADK, etc.), model inheritance \u0026 extends, data types \u0026 numerical precision, timezone settings, grain \u0026 filter context overrides |\n| In progress | Additional dialects, CLI tool |\n| Planned | Authentication \u0026 API tokens, CLI for automation \u0026 CI/CD, DDL view generation (CREATE VIEW from queries), additional BI tool integrations |\n\n---\n\n## Companion Project\n\n### [OrionBelt Analytics](https://github.com/ralfbecher/orionbelt-analytics)\n\nAn 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ralfbecher/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\"\u003e\n\u003c/p\u003e\n\n---\n\n## Development\n\nContributing to OrionBelt or running from source:\n\n```bash\ngit clone https://github.com/ralfbecher/orionbelt-semantic-layer.git\ncd orionbelt-semantic-layer\nuv sync                           # install all deps (dev, docs, ui, flight, drivers)\nuv run orionbelt-api              # start API on :8000\n```\n\n```bash\n# Quality\nuv run pytest                     # run tests\nuv run ruff check src/            # lint\nuv run ruff format src/ tests/    # format\nuv run mypy src/                  # type check\n\n# Docs\nuv sync --extra docs \u0026\u0026 uv run mkdocs serve  # docs on :8080\n```\n\n---\n\n## License\n\nCopyright 2025 [RALFORION d.o.o.](https://ralforion.com)\n\nLicensed under the [Business Source License 1.1](LICENSE). The Licensed Work will convert to Apache License 2.0 on 2030-03-16.\n\nBy contributing to this project, you agree to the [Contributor License Agreement](CLA.md).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ralforion.com\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/ralfbecher/orionbelt-semantic-layer/main/docs/assets/RALFORION_doo_Logo.png\" alt=\"RALFORION d.o.o.\" width=\"200\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralfbecher%2Forionbelt-semantic-layer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fralfbecher%2Forionbelt-semantic-layer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralfbecher%2Forionbelt-semantic-layer/lists"}