{"id":31652199,"url":"https://github.com/sidequery/sidemantic","last_synced_at":"2026-02-21T17:29:16.830Z","repository":{"id":318257960,"uuid":"1069896772","full_name":"sidequery/sidemantic","owner":"sidequery","description":"A universal metrics layer. Compatible with definitions in LookML, MetricFlow, Cube with DuckDB, Snowflake, Clickhouse, Bigquery \u0026 more!","archived":false,"fork":false,"pushed_at":"2026-01-17T16:14:19.000Z","size":4746,"stargazers_count":48,"open_issues_count":8,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-17T17:53:57.632Z","etag":null,"topics":["ai","analytics","analytics-engineering","bigquery","clickhouse","data-engineering","duckdb","mcp","postgresql","semantic-layer","snowflake","spark","sql","visualization"],"latest_commit_sha":null,"homepage":"https://sidemantic.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sidequery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-04T20:51:21.000Z","updated_at":"2026-01-17T16:14:23.000Z","dependencies_parsed_at":"2025-10-06T06:15:25.215Z","dependency_job_id":"d2435323-637d-4781-accb-4a3f16e2588f","html_url":"https://github.com/sidequery/sidemantic","commit_stats":null,"previous_names":["sidequery/sidemantic"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/sidequery/sidemantic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidequery%2Fsidemantic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidequery%2Fsidemantic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidequery%2Fsidemantic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidequery%2Fsidemantic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sidequery","download_url":"https://codeload.github.com/sidequery/sidemantic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sidequery%2Fsidemantic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","analytics","analytics-engineering","bigquery","clickhouse","data-engineering","duckdb","mcp","postgresql","semantic-layer","snowflake","spark","sql","visualization"],"created_at":"2025-10-07T09:59:56.252Z","updated_at":"2026-02-21T17:29:16.822Z","avatar_url":"https://github.com/sidequery.png","language":"Python","readme":"# Sidemantic\n\nSQL-first semantic layer for consistent metrics across your data stack. Compatible with many other semantic model formats.\n\n- **Formats:** Sidemantic, Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Snowflake Cortex, Malloy, OSI, AtScale SML, ThoughtSpot TML\n- **Databases:** DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL\n\n[Documentation](https://sidemantic.com) | [GitHub](https://github.com/sidequery/sidemantic) | [Discord](https://discord.com/invite/7MZ4UgSVvF) | [Demo](https://sidemantic.com/demo) (50+ MB download)\n\n![Jupyter Widget Preview](preview.png)\n\n## Should I use Sidemantic\n\nSidemantic is a very ambitious and young semantic layer project. You may encounter rough patches, especially with the more exotic features like converting between semantic model formats.\n\nIssue reports are much appreciated if you try out Sidemantic and hit a snag 🫡\n\n## Quickstart\n\nInstall:\n```bash\nuv add sidemantic\n```\n\nMalloy support (uv):\n```bash\nuv add \"sidemantic[malloy]\"\n```\n\nNotebook widget (uv):\n```bash\nuv add \"sidemantic[widget]\" jupyterlab\nuv run jupyter lab\n```\n\nMarimo (uv):\n```bash\nuv add \"sidemantic[widget]\" marimo\nuv run marimo edit\n```\n\n```python\nimport duckdb\nfrom sidemantic.widget import MetricsExplorer\n\nconn = duckdb.connect(\":memory:\")\nconn.execute(\"create table t as select 1 as value, 'a' as category, date '2024-01-01' as d\")\nMetricsExplorer(conn.table(\"t\"), time_dimension=\"d\")\n```\n\nDefine models in SQL, YAML, or Python:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSQL\u003c/b\u003e (orders.sql)\u003c/summary\u003e\n\n```sql\nMODEL (name orders, table orders, primary_key order_id);\nDIMENSION (name status, type categorical);\nDIMENSION (name order_date, type time, granularity day);\nMETRIC (name revenue, agg sum, sql amount);\nMETRIC (name order_count, agg count);\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eYAML\u003c/b\u003e (orders.yml)\u003c/summary\u003e\n\n```yaml\nmodels:\n  - name: orders\n    table: orders\n    primary_key: order_id\n    dimensions:\n      - name: status\n        type: categorical\n      - name: order_date\n        type: time\n        granularity: day\n    metrics:\n      - name: revenue\n        agg: sum\n        sql: amount\n      - name: order_count\n        agg: count\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePython\u003c/b\u003e (programmatic)\u003c/summary\u003e\n\n```python\nfrom sidemantic import Model, Dimension, Metric\n\norders = Model(\n    name=\"orders\",\n    table=\"orders\",\n    primary_key=\"order_id\",\n    dimensions=[\n        Dimension(name=\"status\", type=\"categorical\"),\n        Dimension(name=\"order_date\", type=\"time\", granularity=\"day\"),\n    ],\n    metrics=[\n        Metric(name=\"revenue\", agg=\"sum\", sql=\"amount\"),\n        Metric(name=\"order_count\", agg=\"count\"),\n    ]\n)\n```\n\u003c/details\u003e\n\nQuery via CLI:\n```bash\nsidemantic query \"SELECT revenue, status FROM orders\" --db data.duckdb\n```\n\nOr Python API:\n```python\nfrom sidemantic import SemanticLayer, load_from_directory\n\nlayer = SemanticLayer(connection=\"duckdb:///data.duckdb\")\nload_from_directory(layer, \"models/\")\nresult = layer.sql(\"SELECT revenue, status FROM orders\")\n```\n\n## CLI\n\n```bash\n# Query\nsidemantic query \"SELECT revenue FROM orders\" --db data.duckdb\n\n# Interactive workbench (TUI with SQL editor + charts)\nsidemantic workbench models/ --db data.duckdb\n\n# PostgreSQL server (connect Tableau, DBeaver, etc.)\nsidemantic serve models/ --port 5433\n\n# Validate definitions\nsidemantic validate models/\n\n# Model info\nsidemantic info models/\n\n# Pre-aggregation recommendations\nsidemantic preagg recommend --db data.duckdb\n\n# Migrate SQL queries to semantic layer\nsidemantic migrator --queries legacy/ --generate-models output/\n```\n\n## Demos\n\n**Workbench** (TUI with SQL editor + charts):\n```bash\nuvx sidemantic workbench --demo\n```\n\n**PostgreSQL server** (connect Tableau, DBeaver, etc.):\n```bash\nuvx sidemantic serve --demo --port 5433\n```\n\n**Colab notebooks:**\n\n[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sidequery/sidemantic/blob/main/examples/notebooks/sidemantic_sql_duckdb_demo.ipynb) SQL + DuckDB\n\n[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sidequery/sidemantic/blob/main/examples/notebooks/lookml_multi_entity_duckdb_demo.ipynb) LookML multi-entity\n\n**SQL syntax:**\n```bash\nuv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/sql/sql_syntax_example.py\n```\n\n**Comprehensive demo:**\n```bash\nuv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/advanced/comprehensive_demo.py\n```\n\n**Symmetric aggregates:**\n```bash\nuv run https://raw.githubusercontent.com/sidequery/sidemantic/main/examples/features/symmetric_aggregates_example.py\n```\n\n**Superset with DuckDB:**\n```bash\ngit clone https://github.com/sidequery/sidemantic.git \u0026\u0026 cd sidemantic\nuv run examples/superset_demo/run_demo.py\n```\n\n**Cube Playground:**\n```bash\ngit clone https://github.com/sidequery/sidemantic.git \u0026\u0026 cd sidemantic\nuv run examples/cube_demo/run_demo.py\n```\n\n**Rill Developer:**\n```bash\ngit clone https://github.com/sidequery/sidemantic.git \u0026\u0026 cd sidemantic\nuv run examples/rill_demo/run_demo.py\n```\n\n**OSI (complex adtech semantic model):**\n```bash\ngit clone https://github.com/sidequery/sidemantic.git \u0026\u0026 cd sidemantic\nuv run examples/osi_demo/run_demo.py\n```\n\n**OSI widget notebook (percent-cell Python notebook):**\n```bash\ngit clone https://github.com/sidequery/sidemantic.git \u0026\u0026 cd sidemantic\nuv run examples/osi_demo/osi_widget_notebook.py\n```\n\nSee `examples/` for more.\n\n## Core Features\n\n- SQL query interface with automatic rewriting\n- Automatic joins across models\n- Multi-format adapters (Cube, MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML)\n- SQLGlot-based SQL generation and transpilation\n- Pydantic validation and type safety\n- Pre-aggregations with automatic routing\n- Predicate pushdown for faster queries\n- Segments and metric-level filters\n- Jinja2 templating for dynamic SQL\n- PostgreSQL wire protocol server for BI tools\n\n## Multi-Format Support\n\nAuto-detects: Sidemantic (SQL/YAML), Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML\n\n```bash\nsidemantic query \"SELECT revenue FROM orders\" --models ./my_models\n```\n\n```python\nfrom sidemantic import SemanticLayer, load_from_directory\n\nlayer = SemanticLayer(connection=\"duckdb:///data.duckdb\")\nload_from_directory(layer, \"my_models/\")  # Auto-detects formats\n```\n\n## Databases\n\n| Database | Status | Installation |\n|----------|:------:|--------------|\n| DuckDB | ✅ | built-in |\n| MotherDuck | ✅ | built-in |\n| PostgreSQL | ✅ | `uv add sidemantic[postgres]` |\n| BigQuery | ✅ | `uv add sidemantic[bigquery]` |\n| Snowflake | ✅ | `uv add sidemantic[snowflake]` |\n| ClickHouse | ✅ | `uv add sidemantic[clickhouse]` |\n| Databricks | ✅ | `uv add sidemantic[databricks]` |\n| Spark SQL | ✅ | `uv add sidemantic[spark]` |\n\n## Testing\n\n```bash\nuv run pytest -v\n```\n","funding_links":[],"categories":["Integrations"],"sub_categories":["Web Clients (WebAssembly)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidequery%2Fsidemantic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsidequery%2Fsidemantic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidequery%2Fsidemantic/lists"}