Write model selectors in YAML, save them with a human-friendly name, and reference them using the
By recording selectors in a top-level
- Legibility: complex selection criteria are composed of dictionaries and arrays
- Version control: selector definitions are stored in the same git repository as the dbt project
- Reusability: selectors can be referenced in multiple job definitions, and their definitions are extensible (via YAML anchors)
Selectors live in a top-level file named
selectors.yml. Each has a
definition, and an optional
selectors:- name: nodes_to_joydefinition: ...- name: nodes_to_a_grecian_urndescription: Attic shape with a fair attitudedefinition: ...
definition is comprised of one or more arguments, which can be one of the following:
- CLI-style: strings, representing CLI-style) arguments
- Key-value: pairs in the form
- Full YAML: fully specified dictionaries with items for
value, operator-equivalent keywords, and support for
intersection to organize multiple arguments.
This simple syntax supports use of the
* operators. It does
This simple syntax does not support any operators or
This is the most thorough syntax, which can include graph and set operators.
definition:method: tagvalue: nightly# Optional keywords map to the `+` and `@` operators:children: true | falseparents: true | falsechildren_depth: 1 # if children: true, degrees to includeparents_depth: 1 # if parents: true, degrees to includechildrens_parents: true | false # @ operator
* operator to select all nodes can be written as:
definition:method: fqnvalue: "*"
exclude keyword is only supported by fully-qualified dictionaries.
It may be passed as an argument to each dictionary, or as
an item in a
union. The following are equivalent:
- method: tagvalue: nightlyexclude:- "@tag:daily"
- union:- method: tagvalue: nightly- exclude:- method: tagvalue: daily
exclude argument in YAML selectors is subtly different from
--exclude CLI argument. Here,
exclude always returns a set difference,
and it is always applied last within its scope.
This gets us more intricate subset definitions than what's available on the CLI,
where we can only pass one "yeslist" (
--select) and one "nolist" (
Here are two ways to represent:
$ dbt run --models @source:snowplow,tag:nightly models/export --exclude package:snowplow,config.materialized:incremental export_performance_timing
- Full YML
selectors:- name: nightly_diet_snowplowdescription: "Non-incremental Snowplow models that power nightly exports"definition:union:- intersection:- '@source:snowplow'- 'tag:nightly'- 'models/export'- exclude:- intersection:- 'package:snowplow'- 'config.materialized:incremental'- export_performance_timing
Then in our job definition:
$ dbt run --selector nightly_diet_snowplow