> 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/build/v1/productize/plan-and-run.md). # Plan & run Before you deploy, validate the whole project on your machine. This catches SQL errors, dependency issues, schema mismatches, and assertion failures early, while they're still cheap to fix in an isolated environment. Run the cycle below in order, and fix each layer before moving to the next. ``` vulcan info check project structure and connection vulcan test unit tests against mock data vulcan evaluate inspect model output vulcan plan detect changes, materialize, run audits vulcan run refresh data on an already-applied shape ``` `plan` and `run` answer different questions, and confusing them is the most common Vulcan mistake. Use `plan` whenever a model, semantic model, metric, check, or `config.yaml` changed: it reviews the change, classifies its impact, and applies the next version. Use `run` only to process new or missing intervals on a shape that's already applied; it never picks up local code changes and isn't a substitute for `plan`. Scheduled production refreshes use `run`. ## 1. Check structure and connection ```bash vulcan info ``` A clean result confirms three things: `config.yaml` is valid, the engine is reachable, and Vulcan recognizes the model directory. Fix anything it reports before going further. ## 2. Run the unit tests ```bash vulcan test ``` This runs your YAML [Unit Tests](/build/v1/productize/unit-test.md) against mock data, with no warehouse access needed. In `orders-analytics`, `vulcan test` runs both tests: ``` test_fct_daily_sales_excludes_cancelled_orders PASS test_rfm_customer_segmentation_champion PASS ``` If a test fails, `vulcan test` prints a diff of expected versus actual output. Fix the model or the expectation, then re-run. ## 3. Inspect the output ```bash vulcan evaluate silver.fct_daily_sales --limit 10 ``` Use this to preview real output and sanity-check it. Ask yourself: are there rows? Are measures reasonable (no negative revenue, shipment rates between 0 and 1)? Are dimensions populated? Does the row count match the grain? ## 4. Plan ```bash vulcan plan ``` `vulcan plan` detects every change, classifies its impact (added, removed, breaking, non-breaking), computes what to materialize, and runs all attached [assertions](/build/v1/productize/assertions.md) against the new data. The output lists the models and seeds to evaluate, plus an audit summary: ``` Plan: 13 models to evaluate, 1 seed to load bronze.orders (full) [new] silver.fct_daily_sales (full) [new] gold.rfm_customer_segmentation (full) [new] Audits: 15 passed, 0 failed ``` What happens at promotion time depends on `vde` in `config.yaml`. With the default `vde: false`, Vulcan writes each model directly under its own name: simpler, and forward-only, but with no virtual-layer safety boundary. With `vde: true` (not supported on `spark` or `trino` gateways), Vulcan builds a versioned physical snapshot and swaps a virtual-layer view to point at it; that's the "apply the virtual update?" prompt you type `y` to confirm. If an assertion fails, add `--verbose` to see the exact query and the failing rows. Fix the source data or the model, then re-run. Always use `vulcan plan` for production changes. It catches failures before bad data lands. Once a plan is applied, use `vulcan run` on a schedule to keep the product's data current without re-planning every time: ```bash vulcan run ``` ## Debugging tools When something looks wrong, three commands narrow it down fast: * **`vulcan render silver.fct_daily_sales`** - shows the exact SQL after macro expansion, so you can confirm a macro like `@revenue_order_filter(...)` expanded correctly. * **`vulcan export dag dag.html`** - writes the dependency graph. Open it to confirm bronze sits at the root and gold depends on silver. A missing model usually means a wrong `FROM` reference. * **`vulcan audit --verbose`** - runs assertions against the current state and prints failing rows. ## Common issues | Issue | Likely cause | Fix | | ----------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ | | Empty model output | Missing upstream model or wrong filter | Run the plan; check ordering and filter logic | | `Relation does not exist` | Upstream not materialized | Run the plan first; check the `FROM` name | | `Column not found` | SELECT and `MODEL` block disagree | Match column names exactly | | Assertion fails unexpectedly | Data variance exceeds the rule | `vulcan audit --verbose` to see the rows | | YAML parse error | Bad indentation in a test or DQ file | Fix indentation; YAML needs consistent spacing | | `vulcan plan` stops on a lint error | A `linter.rules` violation, blocking by default | Fix the flagged file, or move the rule to `linter.warn_rules` if it should only warn | When the plan passes cleanly, the product is ready to ship. --- # 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/build/v1/productize/plan-and-run.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.