Skip to main content

dbt semantic layer

Status

In development (August 2026). The catalog, validator, and compiler surfaces described here are landing now; treat details as subject-to-change until this notice is removed. Warehouse execution is default-off behind ALPHASWARM_DBT_SEMANTIC_LAYER_ENABLED.

In plain English: today, answering "what was the average daily dollar volume for AAPL last quarter?" requires someone (or some agent) to hand-write SQL — and two people can write two different queries that give two different answers. A semantic layer fixes that by defining each business metric once, in a reviewed file, with its exact formula. From then on, everyone — dashboards, operators, AI agents — asks for the metric by name and gets the same governed calculation.

What it is​

A dbt-MetricFlow-style metrics catalog, committed as YAML in the alphaswarm repo, plus a local compiler that turns a metric request into SQL without calling out to any external service:

  • Semantic models — alphaswarm/data/dbt/projects/core/models/metrics/semantic_models.yml declares entities, dimensions, and measures over warehouse tables (for example equity_minute_bars with volume, dollar-volume, and VWAP measures), with a daily time spine (models/semantic/time_spine_daily.sql).
  • Compiler & procedure — alphaswarm/data/dbt/semantic/ holds the catalog loader, a FilterBuilder, time-grain coarsening helpers, a LocalSemanticCompiler (simple / ratio / derived metrics → dbt-inline SQL), and a SemanticLayerProcedure (parse → validate → compile → optionally execute).

Design decisions worth knowing​

  • The legacy semantic_models: spec is the single source of truth; dual-writing the newer nested MetricFlow spec is forbidden.
  • The production compile path is local — no dbt-semantic-interfaces version bump forces fat images. MetricFlow proper is an opt-in escape hatch via pip install 'alphaswarm[dbt-semantic]' (a dedicated extra, deliberately excluded from the full and data-fabric extras).
  • Catalog / validate / compile are read-only and always available; only warehouse execution is flag-gated, and the read paths never touch QuestDB.

Surfaces​

SurfaceWhat it does
data.dbt.list_metrics (MCP)Enumerate the metric catalog with definitions.
data.dbt.compile_metric (MCP)Compile a metric + filters + grain to SQL without executing.
data.dbt.query_metric (MCP)Compile and execute against the warehouse (flag-gated).
GET /dbt/semantic/catalogThe catalog over HTTP.
POST /dbt/semantic/validateValidate a metric request.
POST /dbt/semantic/compileCompile a metric request to SQL.

For agents this pairs naturally with the Query data via MCP recipe: prefer a named metric over raw SQL whenever one exists.

Flags​

FlagDefaultEffect
ALPHASWARM_DBT_SEMANTIC_LAYER_ENABLEDoffGates warehouse execution only (data.dbt.query_metric). Catalog/validate/compile stay available.
dbt var alphaswarm_semantic_layer_enabledfalseKeeps dbt build from materializing the time spine until enabled.

See also​