> 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/concepts/resources/vulcan/guides/plan.md). # Plan `vulcan plan` is the deployment step for project changes. Use it when you changed models, semantics, metadata, tests, checks, or configuration. Vulcan compares your local project with applied state, shows impact, and prepares the next safe version of the data product. ```bash vulcan plan ``` `vulcan plan` does not just run data. It reviews what changed, classifies the impact, and decides what must be built before the next version is exposed. ## Plan modes Vulcan supports two planning modes. The right one depends on whether your project uses a virtual layer.
Without a virtual layer
Models are written directly with their original names.		/pages/M2zZv3tMn89PVTz1YHLs
With a virtual layer
Consumer-facing names stay stable while Vulcan manages versioned physical snapshots behind them.		/pages/xPZPK6qM5buuclaFC9KN
*** ## What `vulcan plan` does When you run `vulcan plan`, Vulcan: 1. Loads your project files and configuration. 2. Builds the dependency graph. 3. Compares local state with applied state. 4. Detects added, removed, direct, indirect, and metadata-only changes. 5. Computes intervals that need backfill or restatement. 6. Shows the plan before anything is applied. If you apply the plan, Vulcan updates the target state using the selected deployment mode. *** ## When to use `vulcan plan` Use `vulcan plan` when: 1. You changed SQL or Python model logic. 2. You added or removed models. 3. You changed semantics, metrics, assertions, or checks. 4. You updated model metadata or data product configuration. 5. You need to review blast radius before deployment. Use [`vulcan run`](/concepts/resources/vulcan/guides/run_and_scheduling.md) when the shape is already applied and you only need to process new data. Simple rule: ``` Changed the project shape? Use plan. Refreshing data on an applied shape? Use run. ``` *** ## What the plan output tells you The plan helps you answer a few key questions: 1. Which models changed directly? 2. Which downstream models are affected indirectly? 3. Are the changes breaking, non-breaking, or metadata-only? 4. Which intervals need data to be built? 5. Can Vulcan reuse existing state, or must it compute new data first? This makes `vulcan plan` the safest way to move local changes into an applied state. *** ## Typical plan flow Most plans follow this path: ``` 1. Read local project 2. Read applied state 3. Compare snapshots and metadata 4. Classify impact 5. Compute backfill or restatement scope 6. Show the plan 7. Apply after confirmation ``` If you apply the plan, Vulcan may also: 1. Materialize changed models. 2. Backfill required intervals. 3. Update consumer-facing objects. 4. Record plan activity and follow-on execution state. *** ## Common plan actions Create a plan: ```bash vulcan plan ``` Plan a bounded interval: ```bash vulcan plan --start 2026-05-01 --end 2026-05-31 ``` Restate a historical window: ```bash vulcan plan --restate-model analytics.orders --start 2026-05-01 --end 2026-05-07 ``` Apply without interactive prompts: ```bash vulcan plan --no-prompts --auto-apply ``` Explain the plan: ```bash vulcan plan --explain ``` *** ## Choosing the right next step Use `vulcan plan` first when the project changed. Then use `vulcan run` after the new shape is applied and you want ongoing scheduled execution. For the broader workflow, see [Data Product Lifecycle](/concepts/resources/vulcan/guides/data-product-lifecycle.md). {% hint style="info" %} If you are new to Vulcan, start with [Get Started](/concepts/resources/vulcan/guides/get-started.md), then return here before your first deployment. {% endhint %} *** ## Related guides * [Plan without Virtual Layer](/concepts/resources/vulcan/guides/plan/plan_guide.md) * [Plan with Virtual Layer](/concepts/resources/vulcan/guides/plan/vulcan_plan_vde_true.md) * [Run and Scheduling](/concepts/resources/vulcan/guides/run_and_scheduling.md) * [Data Product Lifecycle](/concepts/resources/vulcan/guides/data-product-lifecycle.md) --- # 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/concepts/resources/vulcan/guides/plan.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.