Models
How Vulcan models fit together: physical data models, the semantic layer on top of them, and business metrics on top of that.
Vulcan projects build up in 3 layers. Each layer wraps the one below it and adds a different kind of consumer-facing meaning.
What this section covers
Use this section when you need to:
define the SQL/Python transformations that produce your tables and views
expose those tables as business-friendly dimensions and measures
define reusable, time-series metrics on top of those measures
Choose a starting point
How the layers relate
Data Models transform raw data into tables and views with SQL or Python. Every model has a
MODELblock (DDL) and a query (DML). See Data Models.Semantic models wrap a data model and expose it in business-friendly terms: dimensions to filter and group by, measures to aggregate, segments as reusable filters, and joins to other semantic models. See Semantic models.
Business metrics sit on top of semantic models. They combine a measure, a time dimension, and optional grouping dimensions into a single queryable metric for dashboards, reports, and APIs. See Business metrics.
The underlying data models don't change when you add semantic models or metrics on top. Each layer is additive.
Why layer semantic models and metrics on top
Without a semantic layer, every consumer of your data has to remember which table holds a number, what the column is called, how to join it, and how to calculate it correctly. With semantic models and metrics, they ask for "revenue" and it works the same way everywhere.
For developers. Write the calculation once, then reuse it in dashboards, APIs, and reports. Definitions live in code, so PR review covers business logic and git blame works on metric changes.
For business users. Query data without writing SQL. The same definition runs in BI tools, notebooks, and the REST/GraphQL/SQL-wire APIs, so two dashboards never disagree because they wrote slightly different aggregations.
For organizations. One place where a metric is defined, instead of scattered across dashboards. The data team can audit and change a definition without hunting down every consumer.
How it works end to end
Define data models. Write
.sqlor.pyfiles inmodels/with clean, business-friendly column names.Define semantic models. Create YAML files in
models/semantics/that wrap a data model and declare dimensions, measures, segments, and joins.Define metrics. Combine a measure with a time column and a dimension list under
models/metrics/.Validate.
vulcan planparses every definition and fails the plan if a measure references a missing column, a join expression is invalid, or a metric points at a missing measure.Query. Hit the REST, GraphQL, or SQL-wire API, or export to a BI tool.
File organization
Co-locate semantic models with the data models they wrap, and give each metric its own file:
The filename doesn't matter. Vulcan automatically merges all YAML files in models/semantics/ and models/metrics/. Organize by domain (customers.yml, orders.yml) or by function (revenue_metrics.yml), whatever helps you find things.
Last updated
Was this helpful?