sidemantic

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)

Sidemantic ships Claude Code and Codex plugin metadata for two skills (modeler and webapp-builder). See Agent Plugin below to install.

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