Features

Metric Types

Supported Formats

CLI

Sidequery Workbench

# Try the demo (no setup required!)uvx sidemantic workbench --demo# Or with your own modelssidemantic workbench semantic_models/

Query Command

# Query to stdoutsidemantic query examples/multi_format_demo/ --sql"SELECT orders.total_revenue, customers.region FROM orders"# Query to filesidemantic query examples/multi_format_demo/ -q"SELECT orders.total_revenue FROM orders" -o results.csv# Pipe to other toolssidemantic query examples/multi_format_demo/ -q"SELECT * FROM orders"| head -5

PostgreSQL Server

# Start server (demo mode)sidemantic serve --demo# Start with your modelssidemantic serve semantic_models/ --port 5433# With authenticationsidemantic serve semantic_models/ --username admin --password secret

psql -h 127.0.0.1 -p 5433 -U admin -d sidemantic

Other Commands

# Validate all definitionssidemantic validate semantic_models/# Quick infosidemantic info semantic_models/# MCP server for AI integrationsidemantic mcp-serve semantic_models/

Quick Start

Define your semantic layer

# semantic_layer.ymlmodels:  -name:orderstable:ordersprimary_key:order_idrelationships:      -name:customertype:many_to_oneforeign_key:customer_iddimensions:      -name:statustype:categoricalsql:status      -name:order_datetype:timesql:created_atgranularity:daymetrics:      -name:revenueagg:sumsql:amount      -name:order_countagg:countmetrics:  -name:total_revenuesql:orders.revenue

-- semantic_layer.sqlMODEL (name orders, table orders, primary_key order_id);RELATIONSHIP (name customer, type many_to_one, foreign_key customer_id);DIMENSION (name status, type categorical, sql status);DIMENSION (name order_date, typetime, sql created_at, granularity day);METRIC (name revenue, agg sum, sql amount);METRIC (name order_count, agg count);

fromsidemanticimportSemanticLayer,Model,Dimension,Metric,Relationshiplayer=SemanticLayer()orders=Model(name="orders",table="orders",primary_key="order_id",relationships=[Relationship(name="customer",type="many_to_one",foreign_key="customer_id")],dimensions=[Dimension(name="status",type="categorical",sql="status"),Dimension(name="order_date",type="time",sql="created_at",granularity="day"),    ],metrics=[Metric(name="revenue",agg="sum",sql="amount"),Metric(name="order_count",agg="count"),    ])layer.add_model(orders)

Query with SQL

fromsidemanticimportSemanticLayer# Load semantic layerlayer=SemanticLayer.from_yaml("semantic_layer.yml")# Query with familiar SQL - automatically rewrittenresult=layer.sql("""    SELECT revenue, status    FROM orders    WHERE status = 'completed'""")df=result.fetchdf()

Editor Support

uv run python -m sidemantic.schema

# yaml-language-server: $schema=./sidemantic-schema.json

Loading From Multiple Formats

fromsidemanticimportSemanticLayer,load_from_directory# Point at a directory with mixed formats (Cube, LookML, Hex, MetricFlow, etc.)layer=SemanticLayer(connection="duckdb:///data.db")load_from_directory(layer,"semantic_models/")# That's it! Automatically:# - Discovers all semantic layer files# - Detects format (Cube, Hex, LookML, MetricFlow, Sidemantic)# - Parses with the right adapter# - Infers relationships from foreign key naming (customer_id -> customers)# - Ready to query!result=layer.query(metrics=["orders.revenue"],dimensions=["customers.region"])

Manual Adapter Usage

fromsidemantic.adapters.cubeimportCubeAdapterfromsidemantic.adapters.metricflowimportMetricFlowAdapterfromsidemantic.adapters.sidemanticimportSidemanticAdapter# From Cubecube_adapter=CubeAdapter()graph=cube_adapter.parse("cube_schema.yml")# From MetricFlow (dbt)mf_adapter=MetricFlowAdapter()graph=mf_adapter.parse("semantic_models.yml")# From native Sidemanticnative_adapter=SidemanticAdapter()graph=native_adapter.parse("semantic_layer.yml")

Advanced Features

Complex Metrics

models:  -name:orderstable:ordersprimary_key:order_idmetrics:# Model-level aggregations      -name:revenueagg:sumsql:amount      -name:completed_revenueagg:sumsql:amountfilters:["status = 'completed'"]# Graph-level metricsmetrics:# Simple reference (dependencies auto-detected)  -name:total_revenuesql:orders.revenue# Ratio  -name:conversion_ratetype:rationumerator:orders.completed_revenuedenominator:orders.revenue# Derived (dependencies auto-detected from formula!)  -name:profit_margintype:derivedsql:"(revenue - cost) / revenue"# Cumulative  -name:running_totaltype:cumulativesql:orders.revenuewindow:"7 days"

Automatic Joins

models:  -name:orderstable:ordersprimary_key:order_idrelationships:      -name:customertype:many_to_oneforeign_key:customer_id  -name:customerstable:customersprimary_key:customer_idrelationships:      -name:regiontype:many_to_oneforeign_key:region_id

# Automatically joins orders -> customers -> regionsresult=layer.sql("""    SELECT orders.revenue, regions.region_name    FROM orders""")

Relationship Types

Feature Examples

Segments - Reusable Filters

models:  -name:orderssegments:      -name:completedsql:"{model}.status = 'completed'"description:"Only completed orders"      -name:high_valuesql:"{model}.amount > 100"# Use in querieslayer.compile(metrics=["orders.revenue"], segments=["orders.completed"])

Metric-Level Filters

metrics:  -name:completed_revenueagg:sumsql:amountfilters:["{model}.status = 'completed'"]# Auto-applied!

Jinja2 Templates

metrics:  -name:taxed_revenueagg:sumsql:"{% if include_tax %}amount * 1.1{% else %}amount{% endif %}"# Use with parameterslayer.compile(metrics=["orders.taxed_revenue"], parameters={"include_tax":True})

Inheritance

models:  -name:base_salestable:salesdimensions:[...]  -name:filtered_salesextends:base_sales# Inherits all dimensions!segments:[...]

Hierarchies & Drill-Down

# Define hierarchyDimension(name="country",type="categorical")Dimension(name="state",type="categorical",parent="country")Dimension(name="city",type="categorical",parent="state")# Navigate hierarchymodel.get_hierarchy_path("city")# ['country', 'state', 'city']model.get_drill_down("country")# 'state'model.get_drill_up("city")# 'state'

Relative Dates

# Natural language date filterslayer.compile(metrics=["orders.revenue"],filters=["orders_cte.created_at >= 'last 7 days'"])# Auto-converts to: created_at >= CURRENT_DATE - 7# Supports: "last N days/weeks/months", "this/last/next month/quarter/year", "today", etc.

Ungrouped Queries

# Get raw rows without aggregation (for detail views)sql=layer.compile(metrics=["orders.revenue"],dimensions=["orders.customer_id"],ungrouped=True# Returns raw rows)

Adapter Compatibility

Supported Formats

Feature Compatibility

Database Support

# DuckDB (default)connection:duckdb:///data.duckdb# MotherDuck (cloud DuckDB - requires MOTHERDUCK_TOKEN env var)connection:duckdb://md:database_name# PostgreSQLconnection:postgres://user:pass@localhost:5432/analytics# BigQueryconnection:bigquery://project-id/dataset-id# Snowflakeconnection:snowflake://user:pass@account/database/schema?warehouse=wh# ClickHouseconnection:clickhouse://user:pass@localhost:8123/default# Databricksconnection:databricks://token@server/http-path?catalog=main# Spark SQLconnection:spark://localhost:10000/default

Status

Roadmap

Examples

Testing

uv run pytest -v