Selecting models and tests

How --select, --exclude and --state select the models and tests a command works on, with dbt's selection grammar.

A selection says which models and tests a command works on. Kater reads it as dbt does. You give it with --select, or -s, and you take nodes out of it with --exclude. Each model and each test is one node of the project’s graph, the graph that kater parse writes to target/manifest.json.

# Go to a workspace in your local copy of Kater content
cd connections/snowflake_prod_connection/workspaces/ad_reporting
# Run one saved query
kater run --select query_contracts/spend_by_platform.sql
# Compile the queries that have the tag team=finance
kater compile --select "tag:team=finance,resource_type:query"
# Run the tests of the shared ad_reporting model
kater test --select semantic.ad_reporting
# List the query and everything that it reads
kater ls --select +query_contracts/spend_by_platform.sql

Which commands take it

kater build, kater compile, kater run, kater parse, kater ls, kater test, kater test snapshot, kater sync, kater model list, kater model describe and kater model search take --select, --exclude and --state. kater show takes --select for the one model that it shows.

Without --select, each command works on these:

kater compile and kater run work on your scope, or else on the workspace or modeling folder you are in.
kater test and kater test snapshot work on every test of the connection you are in, or of your only connection.
kater build, kater parse and kater ls read the whole project.
kater sync works on every table that the connection’s connection.yaml selects.
kater model list, describe and search work on your scope.

Use kater ls to see what a selection selects before you run it. It sends nothing to the warehouse.

A bare word

A word with no method is one of these:

A path. A word that has a / or ends in .sql is a file or a folder, such as query_contracts/spend_by_platform.sql or workspaces/ad_reporting. . and .. are paths too. A path is relative to the folder you run the command in. A path that starts with connections/ is from the content root. A folder selects every model in it and in the folders under it.
A typed address. The model’s kind and its name, such as semantic.ad_reporting or query.spend_by_platform.
A name. The name of a model or a test, such as spend_by_platform. * matches any text and ? matches one character, as in a shell: spend_*.

A folder name with no /, such as query_contracts, is a name. Write path:query_contracts or query_contracts/ to select the folder.

Methods

A method is a word, a colon and a value.

Method	Selects	Example
`path:`	The models and tests in a file or a folder.	`path:workspaces/ad_reporting`
`tag:`	The models and tests that have a tag. `key=value` matches that value and the values under it, so `team=marketing` matches `team=marketing/lifecycle`. A key alone matches any value.	`tag:team=finance`, `tag:certified`
`resource_type:`	The nodes of one kind: `query`, `chart`, `semantic`, `kater_dataset`, `db_dataset`, `workspace` or `test`.	`resource_type:query`
`connection:`	The models and tests of one connection, by its folder name.	`connection:snowflake_prod_connection`
`workspace:`	The models and tests of one workspace, by its name.	`workspace:ad_reporting`
`app:`	The queries that an app’s pages read.	`app:monday_brief`
`source:`	A DB dataset, by its name.	`source:google_ads__keyword_report`
`state:`	`state:modified` selects what changed since the state that `--state` names. `state:new` selects only what that state does not hold.	`state:modified`
`result:`	The nodes with this status in `target/run_results.json`: `error`, `fail`, `warn`, `skipped`, `success` or `pass`.	`result:fail`

See Structured model tags for how tags work.

Graph operators

A graph operator adds the nodes around a node.

Operator	Adds	Example
`+x`	What x reads, at any depth.	`+query.spend_by_platform`
`2+x`	What x reads, two steps up.	`2+query.spend_by_platform`
`x+`	What reads x, at any depth.	`semantic.ad_reporting+`
`x+1`	What reads x, one step down.	`semantic.ad_reporting+1`
`@x`	What reads x, and everything those nodes read.	`@semantic.ad_reporting`

An operator works on a bare word and on a method, such as +tag:team=finance or state:modified+.

Union and intersection

A space is a union. --select "query.spend_by_platform query.paid_media_spend_trend" selects both queries.
A comma is an intersection. --select "tag:team=finance,resource_type:query" selects only the queries that have the tag.
Repeat --select for more. --select a.sql --select b.sql is the same as --select "a.sql b.sql".

Put a selection with a space in quotes, so the shell gives it as one value.

A term that matches nothing

A term that selects no model or test prints a warning, as dbt’s does, and the command goes on with the other terms. When a name or a path is close to one in the project, the warning gives it:

15:20:03  Warning: --select spend_by_platfrom matches no object. Did you mean spend_by_platform?

A command whose whole selection selects nothing says “Nothing to do.” and exits 0. state: and result: give no warning, because a branch that changed nothing and a run with no failure are not mistakes. With --warn-error, a warning makes the command exit 1, so a CI step stops on a mistyped selection.

Exclude

--exclude takes the same words as --select. Kater selects first, then takes out each node that --exclude selects.

# Run every saved query in the workspace, and leave out the charts
kater run --select . --exclude resource_type:chart

State

state:modified and state:new compare the project with an earlier state. --state names that state:

--state git:REF compares with the files where this branch left REF, such as git:main. It counts the files committed since then, the files changed but not committed, and new files.
--state FOLDER compares with the manifest.json in that folder, from an earlier kater parse. Make that manifest with a parse of the whole project. A node that the manifest does not hold counts as new.

# Run the tests of what this branch changed since it left main, and of what reads it
kater test --select state:modified+ --state git:main
# Run the merge check: only those tests whose compiled SQL moved since their last pass
kater test --select state:modified+ --state git:main --stale

Tests

A test run selects tests as dbt does:

A model selects its tests. --select semantic.ad_reporting runs the shared layer’s tests of that model, and each person’s that you can read.
A test file selects its tests. Give its path, or path: and its path.
A test name selects that test. --select path:connections/snowflake_prod_connection/modeling/kater_objects/tests/ad_reporting.sql,july_2026_totals_by_platform selects one test of one file.
One connection for each run. A run stops when a selection reaches the tests of more than one connection. Add connection:NAME to the selection, such as --select connection:snowflake_prod_connection,tag:team=marketing.

Other collection flags

Other flags that take more than one value take one value for each flag, such as --sources, --key and --add-fields: --key platform --key currency.