Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 41 ยท Projects and Models

Selecting Nodes: --select, Graph Operators and Tags

Master dbt node selection syntax: model names, the + and @ graph operators, tags, paths, resource types, intersections, exclusions, YAML selectors and state:modified.

Real projects have hundreds of nodes, and you rarely want to build all of them. Selection is how you tell dbt which ones: one model, a model with its ancestors, everything tagged daily, only what you changed. The same syntax works for run, test, build, ls, compile, seed and snapshot, so it is worth learning well.

The basics

Terminal
dbt run --select fct_orders              # one model
dbt run --select fct_orders dim_customers   # a union: either
dbt run --exclude fct_orders             # everything except
dbt ls  --select fct_orders              # preview what would run

Listing with spaces gives a union. A comma between two selectors gives an intersection:

Terminal
dbt build --select tag:daily,marts       # tagged daily AND in the marts folder
dbt build --select tag:daily tag:hourly  # tagged daily OR hourly

Graph operators: + and friends

The plus sign walks the dependency graph.

Selector Meaning
fct_orders Just that model
+fct_orders The model and all its ancestors (upstream)
fct_orders+ The model and all its descendants (downstream)
+fct_orders+ Ancestors, model and descendants
2+fct_orders The model and ancestors up to 2 levels back
fct_orders+1 The model and its direct children
@fct_orders The model, its descendants, and all ancestors of those descendants

Use +model when a model needs everything it depends on to be built first (a fresh developer schema). Use model+ after changing a model, to rebuild everything affected. @model is mainly for CI: it builds everything needed to test a change from scratch.

Let us implement these operators to see exactly which nodes they pick. This is a plain-Python stand-in (not dbt) for graph selection:

Python Stand-in: the + operators on a graph

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that @fct_orders also brings in stg_customers, which is an ancestor of the descendant dim_customers. That is what makes it useful for tests: it includes everything needed to rebuild the downstream world from scratch.

Selecting by method

A selector can have a method before a colon:

Terminal
dbt build --select tag:daily                 # by tag
dbt build --select path:models/marts         # by folder path
dbt build --select models/marts              # path shorthand
dbt build --select package:shop_analytics    # by package
dbt build --select config.materialized:table # by a config value
dbt build --select resource_type:model       # models only
dbt build --select source:shop+              # sources and everything downstream
dbt test  --select test_type:singular        # only singular tests
dbt build --select fqn:shop_analytics.marts.* # by fully qualified name
dbt build --select "orders*"                 # wildcard on names

Methods can be combined with the graph operators: +tag:finance means every model tagged finance and all their ancestors.

Selecting by state

If you save the artifacts (manifest.json) of a previous run (for example from production), dbt can compare and select only what changed:

Terminal
dbt build --select state:modified+ --state ./prod-artifacts
dbt build --select state:new --state ./prod-artifacts

state:modified+ picks every model whose code or config changed since the saved manifest, plus everything downstream. This is the secret behind fast CI: instead of rebuilding 500 models, you build the five that a pull request affects. Combined with --defer, upstream models that were not selected are read from production instead of being rebuilt. Slice B of this course covers it in a CI lesson.

Other state-related selectors are result:error, result:fail and source_status:fresher+, which use run_results.json and freshness results.

Excluding

--exclude takes the same syntax and subtracts from the selection:

Terminal
dbt build --select marts --exclude tag:slow
dbt build --select +fct_orders --exclude stg_legacy_*

YAML selectors

Long command lines are hard to remember. Put a named selection in selectors.yml:

YAML
selectors:
  - name: nightly
    description: "Everything tagged daily, except slow models"
    default: false
    definition:
      union:
        - method: tag
          value: daily
        - exclude:
            - method: tag
              value: slow

Then run it by name:

Terminal
dbt build --selector nightly

Selectors give jobs a stable meaning in version control, instead of strings scattered in schedulers.

A safe habit: list before you run

Terminal
dbt ls --select +fct_orders --resource-type model

A listing costs nothing and shows exactly what a command will touch. Make it a habit, especially before --full-refresh or before run-operation calls that drop things.

Common mistakes

  • Quoting problems. Wildcards like * and the @ sign need quotes in some shells: --select "stg_*".
  • Spaces versus commas. A space means union, a comma means intersection. tag:a tag:b is not tag:a,tag:b.
  • Forgetting tests. dbt run --select x builds x but does not test it. Use build to include tests.
  • Selecting a view chain without ancestors. dbt run --select fct_orders in a fresh schema fails if its parents were never built. Use +fct_orders the first time.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does dbt build --select model_a+ do?

    A plus after the name selects the model and everything downstream of it.
  2. 2. How do you select models that are tagged daily AND live in the marts folder?

    A comma means intersection; a space means union.
  3. 3. Which selection is most useful in CI to build only what a pull request changed (plus downstream)?

    state:modified+ compares against a saved manifest and picks changed nodes and their descendants.
  4. 4. Where can a reusable named selection be defined?

    selectors.yml holds named selectors that you run with --selector.

Summary

  • --select and --exclude work with most commands; spaces mean union, commas mean intersection.
  • +model selects ancestors, model+ descendants, n+ limits depth, and @model adds ancestors of descendants.
  • Methods such as tag:, path:, config., resource_type: and state: choose nodes by property.
  • selectors.yml stores named, reviewable selections; dbt ls previews any selection.

Next: Sources and Freshness