Sidemantic指标层

Docker

The published image is sidequery/sidemantic on Docker Hub. Mount your models directory as a volume at /app/models:

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

Demo mode (built-in sample data, no volume needed):

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

See examples/docker/ for MCP mode, env vars, building from source, and integration test services.

For Cloudflare Worker + Container deployment, see examples/cloudflare_containers/.

Quickstart

Install:

uv add sidemantic

Malloy support (uv):

uv add "sidemantic[malloy]"

HTTP API server (uv):

uv add "sidemantic[api]"

Notebook widget (uv):

uv add "sidemantic[widget]" jupyterlab
uv run jupyter lab

Marimo (uv):

uv add "sidemantic[widget]" marimo
uv run marimo edit

import duckdb
from sidemantic.widget import MetricsExplorer

conn = duckdb.connect(":memory:")
conn.execute("create table t as select 1 as value, 'a' as category, date '2024-01-01' as d")
MetricsExplorer(conn.table("t"), time_dimension="d")

Define models in SQL, YAML, or Python:

<details> <summary><b>SQL</b> (orders.sql)</summary>

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

<details> <summary><b>YAML</b> (orders.yml)</summary>

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

<details> <summary><b>Python</b> (programmatic)</summary>

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

Demos

Workbench (TUI with SQL editor + charts):

uvx --from "sidemantic[workbench]" sidemantic workbench --demo

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

uvx --from "sidemantic[serve]" sidemantic serve --demo --port 5433

HTTP API server (JSON or Arrow):

uvx --from "sidemantic[api]" sidemantic api-serve --demo --port 4400 --auth-token secret

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

OSI (complex adtech semantic model):

git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
uv run examples/osi_demo/run_demo.py

OSI widget notebook (percent-cell Python notebook):

git clone https://github.com/sidequery/sidemantic.git && cd sidemantic
uv run examples/osi_demo/osi_widget_notebook.py

See examples/ for more.

HTTP API server (JSON or Arrow)

uvx --from "sidemantic[api]" sidemantic api-serve models/ --port 4400 --auth-token secret

HTTP API

Start the API server:

uvx --from "sidemantic[api]" sidemantic api-serve models/ --db data.duckdb --port 4400 --auth-token secret

Compile a structured semantic query:

curl -s http://localhost:4400/compile \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{"dimensions":["orders.status"],"metrics":["orders.total_amount"]}'

Run a structured query as JSON:

curl -s http://localhost:4400/query \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{"dimensions":["orders.status"],"metrics":["orders.total_amount","orders.order_count"]}'

Run a structured query as Arrow IPC:

curl -s http://localhost:4400/query \
  -H "Authorization: Bearer secret" \
  -H "Accept: application/vnd.apache.arrow.stream" \
  -H "Content-Type: application/json" \
  -d '{"metrics":["orders.order_count"]}' \
  > result.arrow

Execute rewritten SQL over HTTP:

curl -s http://localhost:4400/sql \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT status, total_amount FROM orders ORDER BY status"}'