Sidemantic

SQL-first semantic layer for consistent metrics across your data stack.

• Formats: Sidemantic, Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, Snowflake Cortex, Malloy
• Databases: DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL

Documentation | GitHub | Discord

Quickstart

Install:

uv add sidemantic

Define models in SQL, YAML, or Python:

SQL (orders.sql)

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);

YAML (orders.yml)

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

Python (programmatic)

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")

CLI

# Query
sidemantic query "SELECT revenue FROM orders" --db data.duckdb

# Interactive workbench (TUI with SQL editor + charts)
sidemantic workbench models/ --db data.duckdb

# PostgreSQL server (connect Tableau, DBeaver, etc.)
sidemantic serve models/ --port 5433

# 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 sidemantic workbench --demo

PostgreSQL server (connect Tableau, DBeaver, etc.):

uvx sidemantic serve --demo --port 5433

Colab notebooks:

SQL + DuckDB

LookML multi-entity

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

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)
• SQLGlot-based SQL generation and transpilation
• Pydantic validation and type safety
• Pre-aggregations with automatic routing
• Predicate pushdown for faster queries
• Segments and metric-level filters
• Jinja2 templating for dynamic SQL
• PostgreSQL wire protocol server for BI tools

Multi-Format Support

Auto-detects: Sidemantic (SQL/YAML), Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL

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]

Testing

uv run pytest -v