How Sidemantic Works

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

This page is the conceptual spine: if you remember one thing about Sidemantic, remember automatic joins and automatic grouping.

Core Objects

Model: a named dataset (usually a table; can also be a SQL subquery) with a primary_key.
Dimension: a field you can group/filter by (categorical, numeric, boolean, time).
Metric (model-level): an aggregation defined on a single model (sum/count/avg/etc).
Metric (graph-level): a metric defined as a formula over other metrics.
Segment: a named filter you can reuse in queries.
Relationship: declares how two models connect (many-to-one, one-to-many, many-to-many).
Pre-aggregation: a materialized rollup table the planner can route queries to.

Warning

Sidemantic SQL is not generic SQL.

No JOIN keyword: joins are inferred from referenced fields and declared relationships.
GROUP BY is ignored: grouping is derived from the selected dimensions.
DISTINCT is not supported: dimensions are treated as distinct at the query grain.

You trigger joins by referencing fields from multiple models in the same query.

Join inference relies on:

Sidemantic treats metrics as aggregations and dimensions as the grouping keys.

When you write:

SELECT customers.region, orders.revenue
FROM orders

Sidemantic interprets that as: “aggregate orders.revenue grouped by customers.region”.

Fan-out happens when you join one row to many rows (e.g. orders → order_items). Naive SQL sum(orders.amount) would double count.

Sidemantic uses symmetric aggregates to protect metric correctness in fan-out joins (see Fan-out & Symmetric Aggregates).

High-level stages: