Semantic Rails

Semantic Rails is an open-source, agent-first semantic layer, licensed Apache-2.0. You define metrics, dimensions and join paths once, in YAML. Agents then discover those definitions, plan a query and run it as governed SQL through an MCP server, a CLI or an HTTP API, instead of writing joins and metric formulas by hand.

• Runs locally on DuckDB with no account or server. Optional connectors cover Snowflake, BigQuery, Databricks, Postgres, Athena, ClickHouse, MotherDuck and DuckLake.
• No telemetry and no update checks. The engine makes network connections only for what you configure; see Telemetry and network access.
• Beta. See Project status for what is supported and what isn't yet.

Try it in one command

You need uv. It fetches a compatible Python (3.11 or newer) if your system Python is older.

uvx semantic-rails ask --package jaffle_shop "revenue by store name" --run

uvx runs Semantic Rails without installing it; the next section shows how to install it. --package names a bundled sample package; pass your own package with --path.

This groups revenue by store name in the synthetic Jaffle Shop sample, then validates, compiles and runs the plan on DuckDB. It prints how it interpreted the question, the rows and any warnings, then the query call. Check that interpretation before you rely on the numbers; see Known limitations. Without uv, try the browser demo or the hosted MCP endpoint below.

Install

To keep a semantic-rails command on your PATH instead of running it through uvx:

uv tool install semantic-rails

If uv warns that its tool directory isn't on your PATH, run uv tool update-shell and open a new terminal.

Or install it into a project environment. Pin the Python version: on a machine without a uv-managed Python, a bare uv venv can pick up the system Python (3.9 on stock macOS, 3.10 on Ubuntu 22.04), and then the install fails.

uv venv --python 3.12
source .venv/bin/activate
uv pip install semantic-rails

With pip, run python -m pip install semantic-rails inside a Python 3.11+ environment. On Windows, activate the environment with .venv\Scripts\activate; see the agent quickstart for how MCP differs there. CI doesn't cover Windows yet.

Quickstart with your own package

Pass --path on commands that use your own package, or run them inside the package directory. Without either, and without a saved profile, commands stop with no_package_selected and list the ways to choose a package; at an interactive terminal, ask first offers the bundled sample package.

uvx semantic-rails init my_package --yes
uvx semantic-rails project validate --path ./my_package
uvx semantic-rails ask --path ./my_package "total amount by event type" --run

init writes a runnable starter package (YAML models, metrics, examples, tests and CSV data). Edit it to describe your own tables, then rerun project validate.

The interactive wizard, semantic-rails setup --interactive, walks through the same steps and can register the MCP server with Claude Desktop or Codex. Run it from an installed semantic-rails, not through uvx, for the reason given under Claude Desktop below. Inside semantic-rails repl, type author to add models, dimensions, measures, metrics and segments with previews and validation.

Connect your agent

MCP clients may start in another directory, so give the package's absolute path.

Claude Code

claude mcp add semantic-rails -- uvx semantic-rails mcp stdio --path "$PWD/my_package"

Codex CLI

codex mcp add semantic-rails -- uvx semantic-rails mcp stdio --path "$PWD/my_package"

Claude Desktop. Install the command, then let Semantic Rails write the client config:

uv tool install semantic-rails
"$(uv tool dir --bin)/semantic-rails" mcp setup --path "$PWD/my_package" --client claude --mcp query --install --yes

uv tool dir --bin finds the command even when uv's tool directory isn't on your PATH yet. Run mcp setup without --install --yes to preview the change. --client codex, --client claude-code (registers the server at user scope), --client cursor (writes ~/.cursor/mcp.json, so the manual Cursor config below is optional) and --client both (Claude Desktop and Codex) also work, and --mcp both adds the Architect MCP, which can edit package files. Don't run mcp setup --install through uvx: the config would point into uv's cache, which uv cache clean deletes.

Cursor. Install the command and print the two absolute paths the config needs:

uv tool install semantic-rails
echo "$(uv tool dir --bin)/semantic-rails"
echo "$PWD/my_package"

Then add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "semantic-rails": {
      "command": "/absolute/path/to/semantic-rails",
      "args": ["mcp", "stdio", "--path", "/absolute/path/to/my_package"]
    }
  }
}

Hosted demo (no install). https://semantic-rails.com/mcp is a public Streamable HTTP endpoint over the same synthetic Jaffle Shop data. It is anonymous and rate-limited, and it can't load your package.

claude mcp add --transport http semantic-rails-demo https://semantic-rails.com/mcp
codex mcp add semantic-rails-demo --url https://semantic-rails.com/mcp

The agent loop, tool policy and HTTP routes are in docs/AGENT_QUICKSTART.md. The full MCP contract, including semantic-rails serve --port 8091 for a local /mcp endpoint, is in docs/MCP_INTERFACE.md.

How it works

An agent works through separate, inspectable steps instead of one SQL string:

discover -> plan -> execute

• discover maps business terms to governed metric, dimension and segment IDs. inspect opens one object's card when the agent needs its aggregations, values or time roles.
• plan drafts a query call from a natural-language question and checks the draft against the question. Run the draft when its status is ok and it has no warnings; otherwise the response says what the draft misses. valid-values (and, over HTTP and the CLI, build-options) guide step-by-step builders instead.
• execute (the CLI's query, HTTP /api/v1/query) validates, compiles and runs the call where the package's connection lives. It rejects unknown fields, dimension mismatches, bad filters and policy failures with structured errors and, where possible, recovery hints.
• validate and compile are optional dry runs of the same checks. validate returns the diagnostics without running anything; compile also renders SQL for the target warehouse. At compact verbosity (the CLI's default) or full, compile returns an explain payload: the chosen join path to each entity, the candidate paths it considered and the relationship contracts along the chosen path. On MCP they are execute modes validate and sql, which default to minimal and leave explain out.

The engine design is in docs/ARCHITECTURE.md, and the supported modeling surface is in docs/CAPABILITIES.md.

How it compares

dbt's Semantic Layer (MetricFlow), Cube, LookML and Malloy are more mature, and they reach warehouses Semantic Rails doesn't support yet: Cube alone connects to Redshift, SQL Server, Microsoft Fabric, MySQL and Trino. dbt, Cube and Looker also connect to far more BI tools and offer caching or pre-aggregation. Semantic Rails is narrower: an engine built around the agent loop above, which you can run locally or embed in Python through semantic_rails.embedding.

The comparison pack asks the same 24 questions of six modeled layers: Semantic Rails, MetricFlow, Cube, Malloy, Snowflake Semantic Views and KtX. Sixteen are answered with models written for them, nine of them chosen to exercise primitives Semantic Rails ships. Eight more change one parameter of a metric those models already use, and each layer answers them with its model unchanged, through its query-time interface only. The pack compares capability, not performance; its support labels describe the authored models, not each layer's limits. The output consistency check compares five layers on the current shared dataset, including Semantic Rails, against an independent SQL answer key: all five match it on all 16, and every frozen-model answer a layer executed matches it too. Those five layers ran live from this repo. Snowflake Semantic Views is a stale capture on an older dataset and is excluded from that count; it matches 14 questions and differs on q07 and q16. The authored models and shared data leave some intended semantics weakly tested, so matching outputs are not a ranking.

Warehouses

DuckDB 1.5.6 or newer is included; this minimum version fixes parallel window execution over empty input blocks used when filling time buckets. Add a connector only when you need it, for example Postgres:

uv tool install 'semantic-rails[postgres]'

Postgres keeps connection.kind: postgres_native and uses ADBC with PyArrow.

The other connector extras are snowflake, snowflake-adbc, bigquery, databricks, athena and clickhouse, and all installs every connector. In a project environment, use uv pip install 'semantic-rails[all]'. MotherDuck and DuckLake use the core duckdb dependency. Keep secrets in environment variables or files, not in package YAML. See docs/DEPLOYMENT.md and docs/ADDING_A_DIALECT.md.

What is tested live

CI checks every warehouse's SQL with dialect rendering tests. Only some warehouses also run the conformance battery against a live server, which compares each answer with DuckDB's; DuckDB and Postgres also run the correctness suite against independent reference SQL. A warehouse without a recent live run is compile-tested only: its SQL is checked, but nothing has executed it lately.

Warehouse	Row filters	Live runs
DuckDB	yes	every engine change in CI
Postgres 16	yes	every engine change in CI
ClickHouse	no	daily, on the latest release
DuckLake	no	daily, on the latest release
BigQuery	no	weekly, on the latest release
Athena	no	weekly, on the latest release
Snowflake (snowflake_native)	no	paused for lack of a test account; last passed on 2026-10-12
Snowflake through ADBC (snowflake_adbc)	yes	on demand only, paused for lack of a test account; CI runs its adapter tests against stubbed connections
Snowflake CLI (snowflake_cli)	no	none: compile-tested only
Databricks	no	paused for lack of a test account
MotherDuck	no	paused for lack of a test account

Row filters bind the caller's trusted values as statement parameters, so the values never enter SQL text; a warehouse without parameter binding refuses a request that a row filter applies to (POLICY_DENIED). See row-filter authoring. Redshift is not supported.

Telemetry and network access

Semantic Rails collects no telemetry and has no update check. The engine opens network connections only to:

• the warehouses configured in your package's connection block;
• DuckDB's extension repository (extensions.duckdb.org): DuckDB downloads an extension it doesn't bundle the first time a query needs one, for example for MotherDuck, DuckLake or remote files.

The hosted demo at semantic-rails.com is a separate deployment with its own privacy notice.

Project status

Semantic Rails is beta software. The supported core is the open-source runtime, the CLI, the MCP stdio and HTTP servers, the /api/v1/* HTTP API, and execution on DuckDB and Postgres, which are tested live on every pull request. The other connectors are supported with guardrails: see what is tested live for each one's live runs. The agent quickstart lists what is experimental or out of scope.

Known limitations

In the current release:

• plan reports the parts of a question its draft doesn't honor, as low_confidence or a PLAN_UNMATCHED_TERMS warning, but its checks don't cover every phrasing, so a draft can still misread a question and report ok, and ask runs it. Check the query call, or ask's "Interpreted as" line, before you rely on the numbers.
• ask runs one query, so it refuses a question that plan answers as several parts (PLAN_PARTS) and lists them: ask each part on its own.
• ask rounds its tables, but JSON results (query, ask --json, MCP execute and the HTTP API) return the warehouse's floating-point values as they are, for example 486468.17999985756 for a currency total.
• Answers trust the data as it is stored: an orphan foreign key counts in entity filters, a join on columns of different types or collations can double totals, and a parent grouped by a value only its children carry counts under each; see known limitations.
• The text filter words refuse search text holding letters that warehouses lower differently, such as Greek sigma, ß and İ, and need ICU on Postgres; see the text words' known limitations.
• A warehouse table named like one of the engine's generated query steps (leaf_<n>, guarded_base, projected, …) can be shadowed by that step: rename the table, or name it with its schema in the model's relation: (analytics.projected).

Roadmap

Work in progress, without dates:

• Packaged agent integrations: Claude Code and Codex plugins and a Claude Desktop bundle. mcp setup already writes the client configs.
• A flagship example: a dbt project on an open dataset, modeled end to end.
• Broader native-model coverage in the comparison pack and a refreshed Snowflake capture on the current dataset.
• Apache Ossie, the incubating Open Semantic Interchange specification: 0.1.1 export and import ship today (docs/OSSIE.md). Next are tested imports of the dbt and Snowflake converters' output, and writing Ossie 0.2.

Questions and proposals are welcome in GitHub Discussions.

Docs

• Getting started
• Agent quickstart
• Package authoring
• MCP interface
• Architect MCP
• The query call
• Query API
• Embedding the engine: semantic_rails.embedding, the one public Python API
• Capabilities
• Architecture
• Benchmark evidence
• Deployment
• Comparison pack
• Changelog

Contributing

CONTRIBUTING.md covers scope, architecture ownership and the validation commands. To work from a source checkout:

git clone https://github.com/semantic-rails/semantic-rails.git
cd semantic-rails
uv sync --group dev
uv run semantic-rails packages
uv run semantic-rails query --package jaffle_shop --query-json '@examples/jaffle_shop_revenue_by_store.json' --verbosity minimal --sql-profile off

Expected package output includes the bundled synthetic fixture:

jaffle_shop

Contributor release smoke for the bundled package:

uv run semantic-rails parse-config --path configs/semantic_rails/jaffle_shop
uv run semantic-rails validate-config --path configs/semantic_rails/jaffle_shop --quiet

Build and verify the exact wheel and sdist before publishing:

uv build --out-dir dist
uv pip install --python .venv/bin/python --reinstall dist/semantic_rails-0.3.4-py3-none-any.whl
uv run python scripts/verify_package_distribution.py --dist-dir dist --no-build

Package naming

Semantic Rails is the public product name. The PyPI distribution is semantic-rails, the Python import package is semantic_rails, and the CLI is semantic-rails.

Support, security and license

Support, issue reporting, conduct and security reporting are documented in SUPPORT.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md.

Semantic Rails is licensed under Apache 2.0; see LICENSE. Everything in this repository is open source, with no gated features. Semantic Rails, Inc., which runs semantic-rails.com, also offers a hosted service; nothing here requires it.