> 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/incremental-by-time/model-selection.md).

# Model selection

Model selection lets you include a subset of your models in a `vulcan plan` so you can test or apply changes without processing everything. In large projects this saves time: a single model change can affect many downstream models, and selection lets you focus on what you are working on. This guide uses the `orders-analytics` example.

## Background

A [plan](/references/dataos-resources/vulcan/core-concepts/plan.md) detects changes between your local project and the deployed environment. When applied, it backfills directly modified models and their downstream dependencies.

* **Directly modified** models are the ones you edited.
* **Indirectly modified** models are downstream of what you changed, so they need reprocessing.

You filter which directly modified models to include; Vulcan figures out the indirect ones. Selection works on the dependency graph, so selecting a model pulls in everything downstream of it. In the example, the chain is `raw.raw_orders → sales.daily_sales → sales.weekly_sales`: changing `raw.raw_orders` affects `daily_sales`, and changing `daily_sales` affects `weekly_sales`.

{% hint style="info" %}
The selector syntax below also works for the `vulcan plan --allow-destructive-model` and `--allow-additive-model` flags.
{% endhint %}

{% hint style="warning" %}
When `on_destructive_change` or `on_additive_change` is set to `error`, use `--allow-destructive-model <model>` or `--allow-additive-model <model>` to explicitly permit the change for a single model in one plan run.
{% endhint %}

## Syntax

Selections use `--select-model` in `vulcan plan`.

**No selection (default):**

```bash
vulcan plan dev
```

Vulcan includes all directly modified models in the project plus their downstream dependents — nothing is filtered out.

**By name:**

```bash
vulcan plan dev --select-model "sales.daily_sales"
vulcan plan dev --select-model "sales.daily_sales" --select-model "raw.raw_orders"
```

Vulcan includes only the named model(s) as directly modified; upstream models that were also changed but not selected are excluded, while downstream dependents of the selected model are still pulled in as indirectly modified.

**Wildcards** with `*`:

```bash
vulcan plan dev --select-model "raw.*"          # all models in the raw schema
vulcan plan dev --select-model "sales.*_sales"  # all models ending in _sales
vulcan plan dev --select-model "*daily*"        # all models containing daily
```

Vulcan includes all models whose fully-qualified name matches the pattern, plus their downstream dependents; models that do not match are excluded even if they were modified.

**Tags** with `tag:`:

```bash
vulcan plan dev --select-model "tag:seed"
vulcan plan dev --select-model "tag:reporting*"
```

Vulcan includes all modified models carrying the specified tag, plus their downstream dependents; untagged models are excluded from the plan.

**Upstream and downstream** with `+`. `+model` includes upstream dependencies, `model+` includes downstream dependents, and `+model+` includes both:

```bash
vulcan plan dev --select-model "+sales.daily_sales"    # raw.raw_orders, daily_sales
vulcan plan dev --select-model "sales.daily_sales+"    # daily_sales, weekly_sales
vulcan plan dev --select-model "+sales.daily_sales+"   # all three
```

`+sales.daily_sales` includes the model and every upstream dependency (e.g. `raw.raw_orders`); `sales.daily_sales+` promotes every downstream dependent (e.g. `sales.weekly_sales`) into the directly modified set; `+sales.daily_sales+` combines both directions.

**Git changes** with `git:`. This includes untracked files (new models), uncommitted changes, and committed changes that differ from the target branch:

```bash
vulcan plan dev --select-model "git:feature"     # changed in the feature branch
vulcan plan dev --select-model "git:feature+"    # changed models + downstream
```

Vulcan includes only the models that differ between the current branch and the target branch (including new, uncommitted, or committed-but-diverged files), plus their downstream dependents; unchanged models are excluded.

**Operators** combine conditions: `&` (and), `|` (or), `^` (not):

```bash
vulcan plan dev --select-model "(tag:finance & ^tag:deprecated)"
vulcan plan dev --select-model "(+sales.daily_sales | sales.weekly_sales+)"
vulcan plan dev --select-model "^(tag:test) & sales.*"
```

## How selection reads in plan output

With no selection, the plan includes every directly modified model plus its downstream dependencies:

```
Models:
├── Directly Modified:
│   ├── sales.daily_sales
│   └── raw.raw_orders
└── Indirectly Modified:
    └── sales.weekly_sales
```

Selecting only `sales.daily_sales` excludes `raw.raw_orders` (you changed it but did not select it) while still pulling `weekly_sales` in as indirectly modified, because it is downstream of `daily_sales`:

```
Models:
├── Directly Modified:
│   └── sales.daily_sales
└── Indirectly Modified:
    └── sales.weekly_sales
```

`sales.daily_sales+` promotes `weekly_sales` into the directly modified set, because the downstream indicator selects it directly. A `tag:` or `git:` selector picks the matching models, and Vulcan adds their downstream dependencies automatically.

## Backfill selection

By default Vulcan backfills every model in a plan. `--backfill-model` limits which models actually backfill, while `--select-model` controls which appear in the plan. This lets you see the full impact but process only what you are testing. Upstream models are always backfilled when a selected model needs them.

{% hint style="warning" %}
`--backfill-model` only works in development environments, not `prod`.
{% endhint %}

**Default (no `--backfill-model`):** all modified models in the plan are backfilled across their missing date ranges.

```bash
vulcan plan dev
```

```
Models needing backfill (missing dates):
├── sales__dev.daily_sales: 2025-01-01 - 2025-01-15
└── sales__dev.weekly_sales: 2025-01-01 - 2025-01-15
```

Vulcan includes every model that appears in the plan; nothing is skipped.

**`--backfill-model "sales.daily_sales"`:** only `daily_sales` is backfilled; downstream models (`weekly_sales`) remain in the plan and run on the new snapshot but use existing data for any un-backfilled intervals.

```bash
vulcan plan dev --backfill-model "sales.daily_sales"
```

```
Models needing backfill (missing dates):
└── sales__dev.daily_sales: 2025-01-01 - 2025-01-15
```

**`--backfill-model "+sales.daily_sales"`:** backfills `daily_sales` and all its upstream dependencies (e.g. `raw.raw_orders`), ensuring the full upstream chain is current before `daily_sales` processes.

```bash
vulcan plan dev --backfill-model "+sales.daily_sales"
```

```
Models needing backfill (missing dates):
├── raw__dev.raw_orders: 2025-01-01 - 2025-01-15
└── sales__dev.daily_sales: 2025-01-01 - 2025-01-15
```

## Best practices

1. **Start small.** Select only the model you are testing, then expand.
2. **Use wildcards** to select groups of related models without listing each.
3. **Include dependencies** with `+` when you need the upstream or downstream chain.
4. **Limit backfill** with `--backfill-model` in dev to save time and compute.
5. **Use tags** to organize models so you can select them together.

## Related docs

* [Plan](/references/dataos-resources/vulcan/core-concepts/plan.md): how the plan classifies and applies the selected changes.
* [Incremental by time](/references/dataos-resources/vulcan/incremental-by-time.md): how backfill intervals are computed.


---

# 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/incremental-by-time/model-selection.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.