Skip to content
Back to search

sidequery

MarketplaceWorks with Claude CodeGitHub

The universal metrics layer. Compatible with 15+ formats: Cube, MetricFlow, LookML, Omni, BSL, LDM, Cortex, Malloy, OSI, SML, TML, Hex, Rill, Superset

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. Its scripts were only partly scanned.

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/sidequery/sidemantic 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/sidequery/sidemantic'

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/sidequery--sidemantic/badge.svg)](/listings/sidequery--sidemantic)

HTML

<a href="/listings/sidequery--sidemantic"><img src="/api/listings/sidequery--sidemantic/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

See it working before writing anything — one command creates a complete demo project (models, sample DuckDB data, golden tests) and runs a first query:

uvx sidemantic demo

Start from your own data — Sidemantic introspects it and generates models with inferred dimensions, metrics, and relationships:

uvx sidemantic init analytics --from data/*.csv     # also Parquet, JSON, DuckDB
cd analytics
sidemantic query "SELECT orders.record_count FROM orders"
sidemantic test              # golden-query assertions
sidemantic validate --live   # models vs. actual database schema
sidemantic serve             # web UI + HTTP API + MCP on one port

Or write a model by hand. Create `models/orders.yml`:

models:
  - name: orders
    sql: |
      select * from (values
        (1, 'paid',    120.00),
        (2, 'paid',     80.00),
        (3, 'pending',  50.00)
      ) as t(id, status, amount)
    primary_key: id
    dimensions:
      - name: status
        type: categorical
        sql: status
    metrics:
      - name: revenue
        agg: sum
        sql: amount
      - name: order_count
        agg: count

Query it directly—no database setup or package installation required:

uvx sidemantic query \
  "SELECT orders.status, orders.revenue, orders.order_count
   FROM orders
   ORDER BY orders.status" \
  --models ./models
status,revenue,order_count
paid,200.00,2
pending,50.00,1

From here, inspect generated warehouse SQL or open an interactive explorer:

# Compile without executing
uvx sidemantic query \
  "SELECT orders.status, orders.revenue FROM orders" \
  --models ./models --dry-run

# Explore in the terminal
uvx --from "sidemantic[workbench]" sidemantic workbench ./models

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.

.claude-plugin/marketplace.json · Manifest · 14 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. {
  2. "name": "sidequery",
  3. "owner": {
  4. "name": "Sidequery",
  5. "email": "hello@sidemantic.com"
  6. },
  7. "plugins": [
  8. {
  9. "name": "sidemantic",
  10. "source": "./plugins/sidemantic",
  11. "description": "Build, validate, and query Sidemantic semantic models, and generate analytics webapps from them. Ships the modeler and webapp-builder skills."
  12. }
  13. ]
  14. }
README.md · README · 444 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. # Sidemantic
  2. Sidemantic is an open-source semantic runtime. Define governed metrics once—or import the semantic models you already have—and query them consistently from SQL, the CLI, Python, HTTP, PostgreSQL clients, notebooks, BI tools, and AI agents.
  3. - **Bring existing models:** Power BI TMDL/DAX, Cube, dbt MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Snowflake Cortex, Malloy, Apache Ossie, AtScale SML, and ThoughtSpot TML
  4. - **Or author natively:** concise YAML, semantic SQL DDL, or Python
  5. - **Run on your warehouse:** DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL, and ADBC sources
  6. - **Consume metrics anywhere:** semantic SQL, CLI, Python, HTTP/Arrow, PostgreSQL wire protocol, MCP, notebooks, TypeScript/WASM, and embedded analytics
  7. [Documentation](https://sidemantic.com) | [GitHub](https://github.com/sidequery/sidemantic) | [Docker Hub](https://hub.docker.com/r/sidequery/sidemantic) | [Discord](https://discord.com/invite/7MZ4UgSVvF) | [Demo](https://sidemantic.com/demo) (50+ MB data download, runs in your browser with Pyodide + DuckDB)
  8. ![Jupyter Widget Preview](preview.png)
  9. Sidemantic ships Claude Code and Codex plugin metadata for two skills (`modeler` and `webapp-builder`). See [Agent Plugin](#agent-plugin) below to install.
  10. Contributors working on browser surfaces should read the [UI architecture and canonical ownership map](docs/ui-architecture.md).
  11. ## 60-second quickstart
  12. See it working before writing anything — one command creates a complete demo
  13. project (models, sample DuckDB data, golden tests) and runs a first query:
  14. ```bash
  15. uvx sidemantic demo
  16. ```
  17. Start from your own data — Sidemantic introspects it and generates models with
  18. inferred dimensions, metrics, and relationships:
  19. ```bash
  20. uvx sidemantic init analytics --from 'data/*.csv' # also Parquet, JSON, DuckDB
  21. cd analytics
  22. uvx sidemantic query "SELECT orders.record_count FROM orders"
  23. uvx sidemantic test # golden-query assertions
  24. uvx sidemantic validate --live # models vs. actual database schema
  25. uvx --from "sidemantic[api,mcp]" sidemantic serve # web UI + HTTP API + MCP on one port
  26. ```
  27. Or write a model by hand. Create `models/orders.yml`:
  28. ```yaml
  29. models:
  30. - name: orders
  31. sql: |
  32. select * from (values
  33. (1, 'paid', 120.00),
  34. (2, 'paid', 80.00),
  35. (3, 'pending', 50.00)
  36. ) as t(id, status, amount)
  37. primary_key: id
  38. dimensions:
  39. - name: status
  40. type: categorical
  41. sql: status
  42. metrics:
  43. - name: revenue
  44. agg: sum
  45. sql: amount
  46. - name: order_count
  47. agg: count
  48. ```
  49. Query it directly—no database setup or package installation required:
  50. ```bash
  51. uvx sidemantic query \
  52. "SELECT orders.status, orders.revenue, orders.order_count
  53. FROM orders
  54. ORDER BY orders.status" \
  55. --models ./models
  56. ```
  57. ```csv
  58. status,revenue,order_count
  59. paid,200.00,2
  60. pending,50.00,1
  61. ```
  62. From here, inspect generated warehouse SQL or open an interactive explorer:
  63. ```bash
  64. # Compile without executing
  65. uvx sidemantic query \
  66. "SELECT orders.status, orders.revenue FROM orders" \
  67. --models ./models --dry-run
  68. # Explore in the terminal
  69. uvx --from "sidemantic[workbench]" sidemantic workbench ./models
  70. ```
  71. ## Choose your path
  72. - **Import existing semantic models:** point Sidemantic at a Cube, MetricFlow, LookML, Power BI, Malloy, Rill, or other supported project. Start with the [adapter guide](https://sidemantic.com/sidemantic/adapters).
  73. - **Model tables or SQL:** continue with [models](https://sidemantic.com/sidemantic/models), [dimensions](https://sidemantic.com/sidemantic/dimensions), [metrics](https://sidemantic.com/sidemantic/metrics), and [relationships](https://sidemantic.com/sidemantic/relationships).
  74. - **Query governed metrics:** use the [CLI](https://sidemantic.com/sidemantic/cli), [semantic SQL](https://sidemantic.com/sidemantic/query), or [Python API](https://sidemantic.com/sidemantic/python-api).
  75. - **Explore data:** launch the terminal workbench, notebook widget, or browser UI.
  76. - **Serve other tools:** expose models over the HTTP API, PostgreSQL wire protocol, or MCP server.
  77. Install Sidemantic in a project with `uv add sidemantic`. Optional features are packaged as extras:
  78. - **Interfaces:** `api` (HTTP API and `sidemantic serve`), `mcp` (MCP server), `apps` (MCP apps with charts), `serve` (PostgreSQL wire protocol server), `workbench` (terminal UI), `widget` (Jupyter widget), `charts` (Altair charts for MCP chart tools), and `lsp` (language server)
  79. - **Model formats:** `lookml`, `metricflow`, `malloy`, `dax` (Power BI TMDL/DAX), and `ossie` (Apache Ossie schema validation)
  80. - **Databases:** `postgres`, `bigquery`, `snowflake`, `clickhouse`, `databricks`, `spark`, and `adbc`, or `all-databases` for all of them
  81. - **Engine:** `rust` (Rust engine) and `fast` (compiled SQLGlot)
  82. - **Bundle:** `full` (every interface, format, and engine extra except `serve`, `fast`, and the databases)
  83. Python is the default engine. To use the optional Rust engine, install `uv tool install "sidemantic[rust]"` (CLI) or `uv add "sidemantic[rust]"` (project), then select `--engine rust`. See [Rust engine mode](docs/rust-engine-mode.md).
  84. ## DAX And TMDL
  85. DAX/TMDL support lives behind the `dax` extra because it includes a native Rust parser:
  86. ```bash
  87. uv add "sidemantic[dax]"
  88. ```
  89. Native Sidemantic YAML can preserve DAX expression source text next to the SQL definition Sidemantic queries, for Power BI interoperability:
  90. ```yaml
  91. models:
  92. - name: sales
  93. table: sales
  94. primary_key: id
  95. dimensions:
  96. - name: doubled_amount
  97. type: numeric
  98. sql: amount * 2
  99. expression_language: dax
  100. dax: "'sales'[amount] * 2"
  101. metrics:
  102. - name: revenue
  103. agg: sum
  104. sql: amount
  105. expression_language: dax
  106. dax: "SUM('sales'[amount])"
  107. ```
  108. Power BI TMDL projects can be loaded from a project root or `definition/` folder. Embedded DAX measures, calculated columns, calculated tables, relationships, and TMDL passthrough metadata are parsed and preserved in model metadata:
  109. ```python
  110. from sidemantic import SemanticLayer, load_from_directory
  111. layer = SemanticLayer(connection="duckdb://warehouse.duckdb")
  112. load_from_directory(layer, "powerbi_project/")
  113. print(layer.describe_models(["Sales"]))
  114. ```
  115. TMDL can also round-trip back to disk:
  116. ```python
  117. from sidemantic.adapters.tmdl import TMDLAdapter
  118. TMDLAdapter().export(layer.graph, "exported_tmdl/")
  119. ```
  120. ## CLI
  121. ```bash
  122. # Scaffold a project (optionally generating models from your data)
  123. sidemantic init
  124. sidemantic init --from data/orders.csv --from data/customers.parquet
  125. # Self-contained demo project with sample data
  126. sidemantic demo
  127. # Query as a human-readable table (also supports csv, json, and jsonl)
  128. sidemantic query "SELECT revenue FROM orders" --db data.duckdb --format table
  129. # Query raw files directly (CSV, Parquet, JSON become tables named by file stem)
  130. sidemantic query "SELECT orders.revenue FROM orders" --db data/orders.csv
  131. # Golden-query tests: pin expected metric values so definitions cannot drift
  132. sidemantic test
  133. # Serve teammates and tools on one port: web UI, HTTP API, and MCP
  134. uvx --from "sidemantic[api,mcp]" sidemantic serve models/ --db data.duckdb
  135. # Interactive workbench (TUI with SQL editor + charts)
  136. uvx --from "sidemantic[workbench]" sidemantic workbench models/ --db data.duckdb
  137. # PostgreSQL server (connect Tableau, DBeaver, etc.)
  138. uvx --from "sidemantic[serve]" sidemantic server postgres models/ --port 5433
  139. # HTTP API server (JSON or Arrow)
  140. uvx --from "sidemantic[api]" sidemantic server api models/ --port 4400 --auth-token-file .secrets/api-token
  141. # Validate definitions (--live also checks tables/columns against the database)
  142. sidemantic validate models/
  143. sidemantic validate models/ --live --db data.duckdb
  144. # Model info
  145. sidemantic info models/
  146. # Pre-aggregation recommendations from a log of compiled queries
  147. # (or --connection for Snowflake, BigQuery, Databricks, or ClickHouse query history)
  148. sidemantic preagg recommend --queries queries.sql
  149. # Migrate SQL queries to semantic layer
  150. sidemantic migrate generate legacy/ --output output/
  151. ```
  152. See [the CLI contract](docs/cli.md) for output formats, `--plain`, quiet/verbose
  153. diagnostics, option placement, terminal behavior, environment precedence,
  154. stdin/stdout, exit codes, debugging, and secure credential input.
  155. ## Demos
  156. **Workbench** (TUI with SQL editor + charts):
  157. ```bash
  158. uvx --from "sidemantic[workbench]" sidemantic workbench --demo
  159. ```
  160. **PostgreSQL server** (connect Tableau, DBeaver, etc.):
  161. ```bash
  162. uvx --from "sidemantic[serve]" sidemantic server postgres --demo --port 5433
  163. ```
  164. **HTTP API server** (JSON or Arrow):
  165. ```bash
  166. uvx --from "sidemantic[api]" sidemantic server api --demo --port 4400
  167. ```
  168. **Colab notebooks:**
  169. [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sidequery/sidemantic/blob/main/examples/notebooks/sidemantic_sql_duckdb_demo.ipynb) SQL + DuckDB
  170. [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sidequery/sidemantic/blob/main/examples/notebooks/lookml_multi_entity_duckdb_demo.ipynb) LookML multi-entity
  171. **SQL syntax:**
  172. ```bash
  173. uv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/sql/sql_syntax_example.py
  174. ```
  175. **Comprehensive demo:**
  176. ```bash
  177. uv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/advanced/comprehensive_demo.py
  178. ```
  179. **Symmetric aggregates:**
  180. ```bash
  181. uv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/features/symmetric_aggregates_example.py
  182. ```
  183. **Superset with DuckDB:**
  184. ```bash
  185. git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
  186. uv run examples/superset_demo/run_demo.py
  187. ```
  188. **Cube Playground:**
  189. ```bash
  190. git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
  191. uv run examples/cube_demo/run_demo.py
  192. ```
  193. **Rill Developer:**
  194. ```bash
  195. git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
  196. uv run examples/rill_demo/run_demo.py
  197. ```
  198. **Apache Ossie (complex adtech semantic model):**
  199. ```bash
  200. git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
  201. uv run examples/osi_demo/run_demo.py
  202. ```
  203. **Apache Ossie widget notebook (percent-cell Python notebook):**
  204. ```bash
  205. git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
  206. uv run examples/osi_demo/osi_widget_notebook.py
  207. ```
  208. See `examples/` for more.
  209. ## Core Features
  210. - SQL query interface with automatic rewriting
  211. - Automatic joins across models
  212. - Multi-format adapters (Cube, MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Apache Ossie, AtScale SML, ThoughtSpot TML, Graphene GSQL)
  213. - SQLGlot-based SQL generation and transpilation
  214. - Pydantic validation and type safety
  215. - Pre-aggregations with explicit routing
  216. - Predicate pushdown for faster queries
  217. - Segments and metric-level filters
  218. - Jinja2 templating for dynamic SQL
  219. - PostgreSQL wire protocol server for BI tools
  220. - HTTP API with JSON and Arrow IPC responses
  221. ## Multi-Format Support
  222. Auto-detects: Sidemantic (SQL/YAML), Power BI TMDL, Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Apache Ossie, AtScale SML, ThoughtSpot TML, Graphene GSQL
  223. ```bash
  224. sidemantic query "SELECT revenue FROM orders" --models ./my_models
  225. ```
  226. ```python
  227. from sidemantic import SemanticLayer, load_from_directory
  228. layer = SemanticLayer(connection="duckdb://data.duckdb") # duckdb:///abs/path.duckdb for absolute paths
  229. load_from_directory(layer, "my_models/") # Auto-detects formats
  230. ```
  231. Apache Ossie is registered as format `ossie`; `osi`, `apache-ossie`, and
  232. `open-semantic-interchange` remain accepted aliases. Use an explicit format when
  233. selecting an Ossie scope or execution dialect:
  234. ```bash
  235. sidemantic convert commerce.ossie.yaml \
  236. --from ossie --to sidemantic --output models.yml \
  237. --ossie-scope commerce --ossie-target-dialect bigquery
  238. sidemantic convert models/orders.yml \
  239. --from sidemantic --to ossie --output commerce.ossie.yaml \
  240. --ossie-scope commerce --ossie-expression-dialect BIGQUERY
  241. ```
  242. See the [Apache Ossie compatibility guide](docs/compatibility/ossie.md) for the
  243. pinned schema profiles, validation policies, scope rules, and round-trip limits.
  244. ## Databases
  245. | Database | Status | Installation |
  246. |----------|:------:|--------------|
  247. | DuckDB | ✅ | built-in |
  248. | MotherDuck | ✅ | built-in |
  249. | PostgreSQL | ✅ | `uv add "sidemantic[postgres]"` |
  250. | BigQuery | ✅ | `uv add "sidemantic[bigquery]"` |
  251. | Snowflake | ✅ | `uv add "sidemantic[snowflake]"` |
  252. | ClickHouse | ✅ | `uv add "sidemantic[clickhouse]"` |
  253. | Databricks | ✅ | `uv add "sidemantic[databricks]"` |
  254. | Spark SQL | ✅ | `uv add "sidemantic[spark]"` |
  255. ## Docker
  256. The published image is [`sidequery/sidemantic`](https://hub.docker.com/r/sidequery/sidemantic) on Docker Hub. Mount your models directory as a volume at `/app/models`:
  257. ```bash
  258. docker run -p 5433:5433 -v ./models:/app/models sidequery/sidemantic
  259. ```
  260. Demo mode (built-in sample data, no volume needed):
  261. ```bash
  262. docker run -p 5433:5433 sidequery/sidemantic --demo
  263. ```
  264. See [`examples/docker/`](examples/docker/) for MCP mode, env vars, building from source, and integration test services.
  265. For Cloudflare Worker + Container deployment, see [`examples/cloudflare_containers/`](examples/cloudflare_containers/).
  266. ## HTTP API
  267. These examples use the project created by `uvx sidemantic demo`. Create a
  268. bearer token file, then start the API server:
  269. ```bash
  270. cd sidemantic-demo
  271. mkdir -p .secrets && openssl rand -hex 32 > .secrets/api-token
  272. uvx --from "sidemantic[api]" sidemantic server api models/ --db data/demo.duckdb --port 4400 --auth-token-file .secrets/api-token
  273. ```
  274. In another terminal in `sidemantic-demo`, compile a structured semantic query:
  275. ```bash
  276. curl -s http://localhost:4400/compile \
  277. -H "Authorization: Bearer $(cat .secrets/api-token)" \
  278. -H "Content-Type: application/json" \
  279. -d '{"dimensions":["orders.status"],"metrics":["orders.revenue"]}'
  280. ```
  281. Run a structured query as JSON:
  282. ```bash
  283. curl -s http://localhost:4400/query \
  284. -H "Authorization: Bearer $(cat .secrets/api-token)" \
  285. -H "Content-Type: application/json" \
  286. -d '{"dimensions":["orders.status"],"metrics":["orders.revenue","orders.order_count"]}'
  287. ```
  288. Run a structured query as Arrow IPC:
  289. ```bash
  290. curl -s http://localhost:4400/query \
  291. -H "Authorization: Bearer $(cat .secrets/api-token)" \
  292. -H "Accept: application/vnd.apache.arrow.stream" \
  293. -H "Content-Type: application/json" \
  294. -d '{"metrics":["orders.order_count"]}' \
  295. > result.arrow
  296. ```
  297. Execute rewritten SQL over HTTP:
  298. ```bash
  299. curl -s http://localhost:4400/sql \
  300. -H "Authorization: Bearer $(cat .secrets/api-token)" \
  301. -H "Content-Type: application/json" \
  302. -d '{"query":"SELECT status, revenue FROM orders ORDER BY status"}'
  303. ```
  304. ## Agent Plugin
  305. Sidemantic ships a [plugin bundle](plugins/sidemantic/) with Claude Code and Codex metadata for two skills:
  306. - **`modeler`** — build, validate, and query semantic models
  307. - **`webapp-builder`** — generate analytics webapps from your models
  308. **Install in Claude Code:**
  309. ```bash
  310. claude plugin marketplace add sidequery/sidemantic && claude plugin install sidemantic@sidequery
  311. ```
  312. **Install in Codex:**
  313. ```bash
  314. codex plugin marketplace add sidequery/sidemantic && codex plugin add sidemantic@sidequery
  315. ```
  316. **Use a local clone while developing:**
  317. ```bash
  318. claude --plugin-dir ./plugins/sidemantic
  319. codex plugin marketplace add . && codex plugin add sidemantic@sidequery
  320. ```
  321. The Claude Code plugin manifest lives at `plugins/sidemantic/.claude-plugin/plugin.json`, and its marketplace lives at `.claude-plugin/marketplace.json`.
  322. The Codex plugin manifest lives at `plugins/sidemantic/.codex-plugin/plugin.json`, and its repo-local marketplace lives at `.agents/plugins/marketplace.json`.
  323. The skills also work with other `SKILL.md`-compatible agents by pointing them at `plugins/sidemantic/skills/`.
  324. ## How mature is Sidemantic?
  325. Sidemantic is an ambitious but young semantic layer project. You could encounter rough patches, especially with the more exotic features like converting between semantic model formats or serving semantic layers via the included Postgres protocol server.
  326. ## Testing
  327. ```bash
  328. uv run pytest -v
  329. ```
  330. This prints line coverage for `sidemantic` with missing lines in the terminal.

Ratings and comments

Sign in to rate this skill.

Sign in

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