Selectors

Selectors let you scope commands to specific subsets of your project. They work with plan, build, test, audit, seed, clone, and diff.

Basic usage

sqb build daily_revenue
sqb build daily_revenue customer_status_snapshot
sqb build --select daily_revenue
sqb build --exclude stg_customers

Selectors can be written as positional arguments on compile, plan, build, test, seed, freshness, audit, and check, or with --select (or -s for short) on any command that selects. Both forms accept one or more names, can be combined, and are unioned. --exclude subtracts from the selected set.

When no --select is provided, all models are selected.

Selector types

Name

Select a single resource by name:

sqb build --select fact_orders

Bare names accept glob patterns. This selects every resource whose name starts with intermediate_:

sqb build --select "intermediate_*"

Name globs compose with graph expansion. For example, +intermediate_* selects every matching resource and all of their upstream dependencies. Quote patterns in shell commands so your shell does not expand * against files in the current directory.

Tag

Select all models with a specific tag:

sqb build --select tag:staging
sqb build --select tag:acceptance

Path

Select all models under a directory path:

sqb build --select path:models/marts
sqb build --select models/marts
sqb build --select path:models/intermediate

Any name containing / is treated as a path selector, so path:models/marts and a bare models/marts work the same way. Path selectors require an explicit root directory: models/ for SQL models or python/ for Python nodes. Nested paths work too: models/staging/orders or python/tasks.

Seed and source

sqb build --select seed:waffle_types
sqb build --select source:raw__orders

Job

Select the nodes a job or job group declared under orchestration/ builds. Job names are globally unique, so a bare name works; job: is the explicit form and accepts glob patterns:

sqb build nightly_orders
sqb build --select job:nightly_orders --exclude order_totals
sqb build --select "job:nightly_orders,tag:finance"

A job selects its own select minus its own exclude. A job group selects the union of its jobs. A job or job group declared with targets is selectable only when the command’s target is one of them, as on the server. Job selectors compose with +, , and --exclude like any other selector. A job’s own selection cannot name another job, and path-between selectors cannot start or end at a job.

SQLBuild imports the modules under orchestration/ only when a selector names a job or a name no model, source, seed or function has.

Unit test

sqb test and sqb build select SQL unit tests by name. Test names are globally unique, so a bare name works; test: is the explicit form and accepts glob patterns:

sqb test order_status_rules
sqb test "test:orders_*" stg_customers

Test selectors are unioned with other selectors and cannot use + or ,. Other commands reject them with S013.

Graph expansion

Upstream

Select a model plus all its upstream dependencies:

sqb build --select +daily_activity_rollup

Downstream

Select a model plus all its downstream dependents:

sqb build --select fact_orders+

Bidirectional

sqb build --select +fact_orders+

Graph expansion works with all selector types:

sqb build --select +tag:marts
sqb build --select path:models/staging+

Path-between selectors

Select all models on every path between two nodes:

sqb build --select fact_orders~daily_activity_rollup

With endpoint expansion:

sqb build --select +fact_orders~daily_activity_rollup+

This selects:

• All upstreams of fact_orders
• Every model on the path between fact_orders and daily_activity_rollup
• All downstreams of daily_activity_rollup

This is useful for rebuilding a specific slice of the DAG without manually listing every model in between.

Intersection

Use commas to intersect selector results:

sqb build --select "tag:staging,path:models/finance"

This selects only models that match both conditions - in this case, models tagged staging that are also under the models/finance directory.

Combining select and exclude

# Build all marts except daily_revenue
sqb build --select path:models/marts --exclude daily_revenue

# Build everything upstream of fact_orders, excluding staging models
sqb build --select +fact_orders --exclude tag:staging

Error handling

Unknown resource names, name patterns with no matches, empty paths, and malformed selectors produce clear error messages:

error[S007]: unknown selector name 'nonexistent_model'
error[S007]: unknown selector name 'missing_*'
error[S009]: no models found under path 'models/nonexistent'.
error[S000]: no SQL resources or Python nodes found with tag 'nonexistent_tag'
error[S003]: path selector 'fact_orders~' requires names on both sides of '~'
error[S013]: selector 'order_status_rules' selects a unit test; only `sqb test` and `sqb build` accept unit-test selectors

Unknown names suggest the closest selectable names, including unit tests:

error[S007]: unknown selector name 'order_status_rule'
  = help: did you mean 'order_status_rules'?

If a path selector omits the root directory, SQLBuild asks for the explicit form:

error[S012]: path selectors require an explicit root: use 'models/' or 'python/'