Getting Started
This guide takes you from a clean checkout to a running local semantic runtime and a
first API-backed query against the canonical jaffle_shop proof package.
1. Install dependencies
git clone https://github.com/semantic-rails/semantic-rails.git cd semantic-rails uv venv uv sync --group dev
This repo uses uv for Python environment and dependency management. Install
uv first if your shell does not already have it.
2. Inspect the active package
uv run semantic-rails packages uv run semantic-rails catalog --package jaffle_shop uv run semantic-rails discover --package jaffle_shop --terms store_name
The reference package used in this guide is jaffle_shop
(customers / orders / order_items / products / stores). The repo ships
its configs plus CSV/SQL seed assets; local commands create
data/jaffle_shop.duckdb on first use.
uv run semantic-rails packages should include jaffle_shop.
3. Start the local server
uv run semantic-rails serve --package jaffle_shop --port 8081 curl -s http://127.0.0.1:8081/api/v1/health curl -s http://127.0.0.1:8081/api/v1/ready
Use /api/v1/* for integrations. Root and unversioned
/api/* paths are not public routes.
The health request should return JSON with "ok": true, and readiness should
report the loaded jaffle_shop package.
3b. Optional deployable runtime and MCP server
uv run semantic-rails mcp stdio --package jaffle_shop uv run semantic-rails mcp http --package jaffle_shop --host 127.0.0.1 --port 8091 docker compose up --build
A successful response includes rows, columns, and execution
metadata for revenue grouped by store and month.
Docker and ASGI make the runtime deployable, but this is not a hosted cloud bundle, managed acceleration layer, or full enterprise auth system.
4. Follow the guided builder path
The preferred public flow is no longer "write raw JSON first." Start with discovery, inspect the semantic object, then ask for the next legal move.
curl -s -X POST http://127.0.0.1:8081/api/v1/discover \
-H "Content-Type: application/json" \
-d '{
"terms": "revenue by store"
}'
curl -s -X POST http://127.0.0.1:8081/api/v1/build-options \
-H "Content-Type: application/json" \
-d '{
"query": {
"version": 1,
"select": [
{
"expression": { "measure": "measure.jaffle.revenue_usd" },
"as": "revenue_usd"
}
]
},
"focus_terms": "revenue by store",
"focus_object_id": "measure.jaffle.revenue_usd",
"step": "group_by",
"limit": 6
}'
5. Run a first query
curl -s -X POST http://127.0.0.1:8081/api/v1/query \
-H "Content-Type: application/json" \
-d '{
"query": {
"version": 1,
"select": [
{
"expression": { "measure": "measure.jaffle.revenue_usd" },
"as": "revenue_usd"
}
],
"group_by": ["dimension.jaffle_store_name"],
"time": {
"temporal_role": "temporal_role.jaffle_order_time",
"grain": "month"
},
"order_by": [{ "field": "revenue_usd", "direction": "DESC" }],
"limit": 5
}
}'
Querying a package outside configs/semantic_rails/
The query CLI subcommand currently accepts
--package <id> (a registered package under
configs/semantic_rails/) but does not accept
--path <dir>. parse-config,
validate-config, and mcp http all do.
To query a freshly authored package that lives outside the configs
directory, start the MCP server with --path and call the
execute tool over JSON-RPC:
uv run semantic-rails mcp http --path /path/to/my_package --host 127.0.0.1 --port 8092 &
curl -s -X POST http://127.0.0.1:8092/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "execute",
"arguments": { "query": { "version": 1, "select": [ ... ] } }
}
}'
Alternatively, copy or symlink the package under
configs/semantic_rails/<id>/ and re-run
uv run semantic-rails packages to register it for the
direct query --package <id> path.
6. Run the test suite
uv run pytest -q tests/semantic_rails
What to do next
- Model or extend a package in Package Authoring.
- Look up exact field shapes in Authoring Reference.
- Understand planner behavior in Query Planner.
- Use the staged API path in Agent Actions.