> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/resources/vulcan/models.md). # Models 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
Data Models
The MODEL block, the SELECT query, conventions, and the day-to-day workflow for adding, editing, and deleting models.		/pages/mlqz76FMhqSR4ZqdJg4r
Semantic models
Wrap a Vulcan model with business-friendly dimensions, measures, segments, and joins.		/pages/LJ5qM4d5xFrhYSReGuRw
Business metrics
Time-series metrics built on top of semantic model measures, for dashboards, reports, and APIs.		/pages/UfvIJjp9W6hfrsDsPRy3
## How the layers relate 1. **Data Models** transform raw data into tables and views with SQL or Python. Every model has a `MODEL` block (DDL) and a query (DML). See [Data Models](/references/resources/vulcan/models/data-models.md). 2. **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](/references/resources/vulcan/models/semantic-models.md). 3. **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](/references/resources/vulcan/models/business-metrics.md). 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 1. **Define data models.** Write `.sql` or `.py` files in `models/` with clean, business-friendly column names. 2. **Define semantic models.** Create YAML files in `models/semantics/` that wrap a data model and declare dimensions, measures, segments, and joins. 3. **Define metrics.** Combine a measure with a time column and a dimension list under `models/metrics/`. 4. **Validate.** `vulcan plan` parses 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. 5. **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: ``` project/ ├── models/ # Vulcan data models (.sql files) │ ├── customers.sql │ ├── orders.sql │ ├── events.sql │ │ │ ├── semantics/ # Semantic models (kind: semantic) │ │ ├── customers.yml │ │ └── orders.yml │ │ │ └── metrics/ # Per-metric files │ ├── arr_growth.yml │ ├── churn_analysis.yml │ └── cohort_retention.yml │ └── config.yaml ``` 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. {% hint style="warning" %} **Policies attach to physical models** If your data product uses row filtering or column masking, author policy files under `policies/access/` and attach each policy to a physical model. Semantic and metric models inherit those rules. See [Policies](/references/resources/vulcan/policies.md). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/references/resources/vulcan/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.