Sidemantic Documentation

Interactive Demo

Try Sidemantic in your browser with DuckDB WASM and Pyodide - no installation required.

What is Sidemantic

A semantic layer: define metrics once, query them consistently across tools.

Quickstart

Install Sidemantic, run the demo, and define your first semantic layer.

Configuration

YAML file structure, database connections, models, dimensions, metrics, and CLI configuration for Sidemantic

Database Connections

Connect Sidemantic to DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, and Spark SQL with flexible connection string formats

Workbench

Interactive terminal UI for exploring semantic layers, writing SQL queries, and visualizing results

How Sidemantic Works

The mental model: automatic joins, automatic grouping, correctness with fan-out, and the compilation pipeline.

Models

Define your data sources with models. Learn about dimensions, metrics, relationships, and time granularity.

Dimensions

Dimensions are fields you group and filter by: categorical, numeric, boolean, and time (with granularity suffixes).

Metrics

Define aggregations and calculations. Model-level metrics aggregate data, graph-level metrics combine them with formulas and automatic dependency detection.

Segments

Segments are named filters you can reuse across queries.

Relationships

Define relationships between models for automatic joining.

Fan-out & Symmetric Aggregates

Why fan-out joins double count, what Sidemantic does, how to validate correctness, and when it can be expensive.

Gotchas

Common pitfalls: inferred joins, automatic grouping, fan-out surprises, primary keys, and time grains.

Query

Query the semantic layer using SQL syntax or the Python API

Python API

Complete Python API reference for Sidemantic

Parameters & Templating

What templating exists today, what’s deprecated, and what works in SQL vs programmatic query APIs.

Pre-Aggregations

Materialized rollup tables that store pre-computed aggregations for significant query performance improvements with automatic query routing and refresh strategies.

Pre-Aggregation Recommendations

Automatically analyze query history and get optimal pre-aggregation recommendations with benefit scores.

CLI Workflows

Tools for working with semantic layers from the terminal

Serve (Postgres Wire)

Expose your semantic layer over the PostgreSQL wire protocol for BI tools and clients.

LSP Setup

Editor integration for Sidemantic SQL via the Language Server Protocol.

MCP Server

Enable AI assistants like Claude to query your semantic layer using the Model Context Protocol server

MCP Server Security

Threat model, safe defaults, and least-privilege guidance for running the MCP server.

Migrator

Migrate existing SQL queries to semantic layer by analyzing queries and generating model definitions.

Adapters

Import semantic models from Cube, MetricFlow, LookML, Hex, Rill, Superset, Omni, and BSL into Sidemantic

CI Workflow

How to validate semantic layer changes in PRs and catch breaking model edits early.

Change Management

How to version your semantic layer and avoid breaking dashboards and downstream consumers.

Observability

Capture compiled SQL, tag queries, and debug join and metric planning in production.

YAML Reference

Field-by-field reference for Sidemantic YAML definitions.

SQL DDL Reference

Reference for Sidemantic SQL DDL blocks: MODEL, DIMENSION, METRIC, RELATIONSHIP, SEGMENT.

JSON Schema

Download and use the Sidemantic YAML JSON Schema for editor autocomplete and validation.

Examples

Practical examples of using Sidemantic for semantic layer queries, from basic metrics to advanced cross-model joins and derived metrics.

ADBC Connections

Connect Sidemantic to databases using ADBC (Arrow Database Connectivity) for high-performance Arrow-native data transfer