> 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/dataos-resources/vulcan/core-concepts.md).

# Core concepts

Core concepts are the building blocks of a Vulcan data product. They define how data is transformed, validated, described, and served. The model is the center of gravity: everything else attaches to a model. Get the model right first, because the rest only has something to validate or expose once it exists.

## How the pieces fit together

In most projects the flow looks like this:

1. Build tables or views with **models**, in SQL or Python.
2. Validate logic with **tests** against controlled inputs and expected outputs.
3. Block bad data at write time with **audits**, attached to models as **assertions**.
4. Monitor data over time with **data quality (DQ) checks** (`kind: dq`).
5. Expose curated definitions through the **semantic model and components**.
6. Extend behavior with **macros** and **signals**.

Behind all of this, **plan** decides what changes and what to build, and **state** records what has already been applied.

```mermaid
%%{init: {"theme":"base","themeVariables":{"fontFamily":"PP Neue Montreal, Inter, Helvetica Neue, Arial, sans-serif","fontSize":"14px","primaryColor":"#EDE9E5","primaryTextColor":"#242422","primaryBorderColor":"#242422","lineColor":"#242422","secondaryColor":"#D6CDC6","tertiaryColor":"#FFFFFF","clusterBkg":"#EDE9E5","clusterBorder":"#54DED1","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","padding":12,"nodeSpacing":40,"rankSpacing":50}}}%%
graph LR
    A[Models] --> B[Tests]
    A --> C[Audits + Assertions]
    A --> D[Data Quality]
    A --> E[Semantics]
    A --> F[Macros + Signals]

    classDef primary-teal fill:#54DED1,color:#202F36,stroke:#009293,stroke-width:1.5px,font-weight:600;
    classDef surface      fill:#FFFFFF,color:#242422,stroke:#242422,stroke-width:1px;

    class A primary-teal;
    class B,C,D,E,F surface;
```

## The data quality triplet

Three artifacts look similar but do different jobs. Keep them straight: **DQ checks watch, audits define, assertions attach.**

* An **audit** is the validation rule: a named SQL query in `audits/*.sql` that returns rows when data is bad. It is reusable across models.
* An **assertion** is the attachment of a rule to a model, declared inside a `MODEL (...)` block via `assertions (...)`. It blocks the model when the rule fails.
* A **DQ check** is a declarative profile-and-rule pack in `dq/*.yml` with `kind: dq`. It is non-blocking and monitors quality over time.

See [Assertions](/references/dataos-resources/vulcan/core-concepts/assertions.md) for audits and assertions, and [Data quality](/references/dataos-resources/vulcan/core-concepts/data-quality.md) for DQ checks.

## Pages

| Page                                                                                                                | What it covers                                                                 |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [Plan](/references/dataos-resources/vulcan/core-concepts/plan.md)                                                   | Planning, apply, the virtual layer, backfill, and restatement.                 |
| [State](/references/dataos-resources/vulcan/core-concepts/state.md)                                                 | The state store: how Vulcan tracks what has been applied.                      |
| [Model and kinds](/references/dataos-resources/vulcan/core-concepts/model-and-kinds.md)                             | The `MODEL` block, properties, statements, model kinds, and model types.       |
| [Semantic model and components](/references/dataos-resources/vulcan/core-concepts/semantic-model-and-components.md) | Semantic models, dimensions, measures, segments, joins, metrics, and policies. |
| [Data quality](/references/dataos-resources/vulcan/core-concepts/data-quality.md)                                   | DQ checks (`kind: dq`): rules, dimensions, and profiling.                      |
| [Assertions](/references/dataos-resources/vulcan/core-concepts/assertions.md)                                       | Audits and assertions: built-in and user-defined rules that block bad rows.    |
| [Test](/references/dataos-resources/vulcan/core-concepts/unit-test.md)                                              | Unit tests for model logic against fixtures.                                   |
| [Macros](/references/dataos-resources/vulcan/core-concepts/macros.md)                                               | Vulcan and Jinja macros, plus predefined variables.                            |
| [Built-in macros](/references/dataos-resources/vulcan/core-concepts/built-in-macros.md)                             | Reference for the built-in macro operators and typed Python macros.            |
| [Signals](/references/dataos-resources/vulcan/core-concepts/signals.md)                                             | Custom readiness gates before scheduled models run.                            |


---

# 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/dataos-resources/vulcan/core-concepts.md?ask=<question>&goal=<endgoal>
```

`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.