sidequery/sidemantic repository overview

⁠Sidemantic

Universal SQL-first semantic layer for consistent metrics across your data stack. Define metrics once, query them from anywhere.

GitHub: github.com/sidequery/sidemantic⁠ | Docs: sidemantic.com⁠ | By: Sidequery⁠

⁠What is Sidemantic?

Sidemantic is a universal metrics layer that imports semantic models from 15+ formats (Cube, dbt MetricFlow, LookML, Hex, Rill, Superset, Omni, Malloy, AtScale SML, ThoughtSpot TML, and more) and queries against DuckDB, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, and Spark SQL.

Write SQL against your semantic layer. Sidemantic rewrites queries automatically, handles joins across models, and routes to pre-aggregations when available.

⁠What's in this image?

This image includes all database drivers, the PostgreSQL wire protocol server (to use with any BI tool or other database tool), and the MCP server. Mount your models and go.

⁠Mounting Your Models

The container looks for model files (YAML, SQL, etc.) in /app/models. Use a volume mount (-v) to point it at your local models directory:

# If your models are in ~/my-project/models/
docker run -p 5433:5433 -v ~/my-project/models:/app/models sidequery/sidemantic

# Or from the current directory
docker run -p 5433:5433 -v $(pwd)/models:/app/models sidequery/sidemantic

The -v local/path:/app/models flag maps a folder on your machine into the container. Any .yml, .sql, or other semantic model files in that folder will be auto-detected and loaded.

⁠Quick Start

⁠PostgreSQL compatible server (default uses DuckDB)

docker run -p 5433:5433 -v ./models:/app/models sidequery/sidemantic

Connect with any PostgreSQL client (psql, Tableau, DBeaver, Metabase):

psql -h localhost -p 5433 -U any -d sidemantic

⁠With a connection

docker run -p 5433:5433 \
  -v ./models:/app/models \
  -e SIDEMANTIC_CONNECTION="postgres://user:pass@host:5432/db" \
  sidequery/sidemantic

⁠MCP server (for AI assistants)

docker run -v ./models:/app/models -e SIDEMANTIC_MODE=mcp sidequery/sidemantic

⁠Demo mode

docker run -p 5433:5433 sidequery/sidemantic --demo

⁠Native Notebook Integrations

Sidemantic integrates natively with Jupyter notebooks (via the MetricsExplorer widget and pynb support) and SQL notebooks (sqlnb), so you can query your semantic layer directly in notebook cells without context switching.

⁠Supported Formats

Cube, dbt MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Snowflake Cortex, Malloy, OSI, AtScale SML, ThoughtSpot TML, and Sidemantic's own SQL/YAML/Python formats.

⁠Supported Databases

DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL (also via ADBC).

⁠Environment Variables

⁠Bake models into the image

FROM sidequery/sidemantic
COPY my_models/ /app/models/

⁠Links

• Documentation⁠
• Sidequery⁠
• GitHub⁠
• Discord⁠
• PyPI⁠