Sidemantic - Camada Universal de Métricas
sidequery/sidemantic
Camada semântica universal para métricas consistentes em sua stack de dados
Ver no GitHubMCP Server que funciona como camada semântica universal, permitindo definir métricas uma única vez e usá-las em 15+ formatos (Cube, MetricFlow, LookML, dbt, Power BI, etc). Suporta SQL, YAML e Python para definição de modelos e integra com DuckDB, PostgreSQL, BigQuery, Snowflake e outros bancos de dados.
Instalação
npx convez-ai sidequery/sidemantic1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Centralizar definições de métricas em múltiplas plataformas BI
- Migrar entre ferramentas de BI sem reescrever todas as métricas
- Criar camada semântica consistente acima de múltiplos bancos de dados
- Interoperabilidade entre dbt, Power BI, Cube e outras plataformas
Veredito

Ferramenta robusta para engenheiros de dados e analistas que trabalham com múltiplas plataformas BI. Resolve um problema real de fragmentação de definições de métricas, mas exige familiaridade com semântica de dados e DevOps.
README
A tradução para o português deste README ainda está na fila.
Sidemantic
The universal metrics layer for consistent metrics across your data stack. Compatible with 15+ semantic model formats.
- Supported Formats: Sidemantic (YAML, Python or SQL), Power BI TMDL, Cube, dbt MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Snowflake Cortex, Malloy, OSI, AtScale SML, ThoughtSpot TML
- Databases: DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL (also via ADBC)
Documentation | GitHub | Docker Hub | Discord | Demo (50+ MB data download, runs in your browser with Pyodide + DuckDB)

The installer downloads the skill to ~/.agents/skills/sidemantic-modeler and symlinks it into ~/.claude/skills/.
Quickstart
Install:
uv add sidemantic
Malloy support (uv):
uv add "sidemantic[malloy]"
DAX and Power BI TMDL support (uv):
uv add "sidemantic[dax]"
HTTP API server (uv):
uv add "sidemantic[api]"
Notebook widget (uv):
uv add "sidemantic[widget]" jupyterlab
uv run jupyter lab
Marimo (uv):
uv add "sidemantic[widget]" marimo
uv run marimo edit
import duckdb
from sidemantic.widget import MetricsExplorer
conn = duckdb.connect(":memory:")
conn.execute("create table t as select 1 as value, 'a' as category, date '2024-01-01' as d")
MetricsExplorer(conn.table("t"), time_dimension="d")
Define models in SQL, YAML, or Python:
MODEL (name orders, table orders, primary_key order_id);
DIMENSION (name status, type categorical);
DIMENSION (name order_date, type time, granularity day);
METRIC (name revenue, agg sum, sql amount);
METRIC (name order_count, agg count);
models:
- name: orders
table: orders
primary_key: order_id
dimensions:
- name: status
type: categorical
- name: order_date
type: time
granularity: day
metrics:
- name: revenue
agg: sum
sql: amount
- name: order_count
agg: count
from sidemantic import Model, Dimension, Metric
orders = Model(
name="orders",
table="orders",
primary_key="order_id",
dimensions=[
Dimension(name="status", type="categorical"),
Dimension(name="order_date", type="time", granularity="day"),
],
metrics=[
Metric(name="revenue", agg="sum", sql="amount"),
Metric(name="order_count", agg="count"),
]
)
Query via CLI:
sidemantic query "SELECT revenue, status FROM orders" --db data.duckdb
Or Python API:
from sidemantic import SemanticLayer, load_from_directory
layer = SemanticLayer(connection="duckdb:///data.duckdb")
load_from_directory(layer, "models/")
result = layer.sql("SELECT revenue, status FROM orders")
DAX And TMDL
DAX/TMDL support lives behind the dax extra because it includes a native Rust parser:
uv add "sidemantic[dax]"
Native Sidemantic YAML can preserve DAX expression source text for Power BI interoperability:
models:
- name: sales
table: sales
primary_key: id
dimensions:
- name: doubled_amount
type: numeric
dax: "'sales'[amount] * 2"
metrics:
- name: revenue
dax: "SUM('sales'[amount])"
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:
from sidemantic import SemanticLayer, load_from_directory
layer = SemanticLayer(connection="duckdb:///warehouse.duckdb")
load_from_directory(layer, "powerbi_project/")
print(layer.describe_models(["Sales"]))
TMDL can also round-trip back to disk:
from sidemantic.adapters.tmdl import TMDLAdapter
TMDLAdapter().export(layer.graph, "exported_tmdl/")
CLI
# Query
sidemantic query "SELECT revenue FROM orders" --db data.duckdb
# Interactive workbench (TUI with SQL editor + charts)
uvx --from "sidemantic[workbench]" sidemantic workbench models/ --db data.duckdb
# PostgreSQL server (connect Tableau, DBeaver, etc.)
uvx --from "sidemantic[serve]" sidemantic serve models/ --port 5433
# HTTP API server (JSON or Arrow)
uvx --from "sidemantic[api]" sidemantic api-serve models/ --port 4400 --auth-token secret
# Validate definitions
sidemantic validate models/
# Model info
sidemantic info models/
# Pre-aggregation recommendations
sidemantic preagg recommend --db data.duckdb
# Migrate SQL queries to semantic layer
sidemantic migrator --queries legacy/ --generate-models output/
Demos
Workbench (TUI with SQL editor + charts):
uvx --from "sidemantic[workbench]" sidemantic workbench --demo
PostgreSQL server (connect Tableau, DBeaver, etc.):
uvx --from "sidemantic[serve]" sidemantic serve --demo --port 5433
HTTP API server (JSON or Arrow):
uvx --from "sidemantic[api]" sidemantic api-serve --demo --port 4400 --auth-token secret
Colab notebooks:
SQL syntax:
uv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/sql/sql_syntax_example.py
Comprehensive demo:
uv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/advanced/comprehensive_demo.py
Symmetric aggregates:
uv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/features/symmetric_aggregates_example.py
Superset with DuckDB:
git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
uv run examples/superset_demo/run_demo.py
Cube Playground:
git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
uv run examples/cube_demo/run_demo.py
Rill Developer:
git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
uv run examples/rill_demo/run_demo.py
OSI (complex adtech semantic model):
git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
uv run examples/osi_demo/run_demo.py
OSI widget notebook (percent-cell Python notebook):
git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
uv run examples/osi_demo/osi_widget_notebook.py
See examples/ for more.
Core Features
- SQL query interface with automatic rewriting
- Automatic joins across models
- Multi-format adapters (Cube, MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML, Graphene GSQL)
- SQLGlot-based SQL generation and transpilation
- Pydantic validation and type safety
- Pre-aggregations with explicit routing
- Predicate pushdown for faster queries
- Segments and metric-level filters
- Jinja2 templating for dynamic SQL
- PostgreSQL wire protocol server for BI tools
- HTTP API with JSON and Arrow IPC responses
Multi-Format Support
Auto-detects: Sidemantic (SQL/YAML), Power BI TMDL, Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML, Graphene GSQL
sidemantic query "SELECT revenue FROM orders" --models ./my_models
from sidemantic import SemanticLayer, load_from_directory
layer = SemanticLayer(connection="duckdb:///data.duckdb")
load_from_directory(layer, "my_models/") # Auto-detects formats
Databases
| Database | Status | Installation |
|---|---|---|
| DuckDB | ✅ | built-in |
| MotherDuck | ✅ | built-in |
| PostgreSQL | ✅ | uv add sidemantic[postgres] |
| BigQuery | ✅ | uv add sidemantic[bigquery] |
| Snowflake | ✅ | uv add sidemantic[snowflake] |
| ClickHouse | ✅ | uv add sidemantic[clickhouse] |
| Databricks | ✅ | uv add sidemantic[databricks] |
| Spark SQL | ✅ | uv add sidemantic[spark] |
Docker
The published image is sidequery/sidemantic on Docker Hub. Mount your models directory as a volume at /app/models:
docker run -p 5433:5433 -v ./models:/app/models sidequery/sidemantic
Demo mode (built-in sample data, no volume needed):
docker run -p 5433:5433 sidequery/sidemantic --demo
See examples/docker/ for MCP mode, env vars, building from source, and integration test services.
For Cloudflare Worker + Container deployment, see examples/cloudflare_containers/.
HTTP API
Start the API server:
uvx --from "sidemantic[api]" sidemantic api-serve models/ --db data.duckdb --port 4400 --auth-token secret
Compile a structured semantic query:
curl -s http://localhost:4400/compile \
-H "Authorization: Bearer secret" \
-H "Content-Type: application/json" \
-d '{"dimensions":["orders.status"],"metrics":["orders.total_amount"]}'
Run a structured query as JSON:
curl -s http://localhost:4400/query \
-H "Authorization: Bearer secret" \
-H "Content-Type: application/json" \
-d '{"dimensions":["orders.status"],"metrics":["orders.total_amount","orders.order_count"]}'
Run a structured query as Arrow IPC:
curl -s http://localhost:4400/query \
-H "Authorization: Bearer secret" \
-H "Accept: application/vnd.apache.arrow.stream" \
-H "Content-Type: application/json" \
-d '{"metrics":["orders.order_count"]}' \
> result.arrow
Execute rewritten SQL over HTTP:
curl -s http://localhost:4400/sql \
-H "Authorization: Bearer secret" \
-H "Content-Type: application/json" \
-d '{"query":"SELECT status, total_amount FROM orders ORDER BY status"}'
Agent Skill
Sidemantic ships an agent skill that teaches Claude Code, Codex, and other SKILL.md-compatible agents to build, validate, and query semantic models.
One-liner install (no clone required):
curl -fsSL https://raw.githubusercontent.com/sidequery/sidemantic/main/skills/install.sh | bash
npx / bunx:
npx skills add https://github.com/sidequery/sidemantic --skill sidemantic-modeler
# or
bunx skills add https://github.com/sidequery/sidemantic --skill sidemantic-modeler
How mature is Sidemantic?
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.
Testing
uv run pytest -v
This prints line coverage for sidemantic with missing lines in the terminal.