Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions concepts/rules.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -196,9 +196,9 @@ need to execute SQL against controlled data. Use an audit when the answer depend
A finding contains a stable code, project-relative path, line, column, explanation, and remediation.
This makes the same requirement usable in a terminal, JSON output, CI annotation, or agent workflow.

Intentional departures remain explicit. Exact exceptions and path-scoped ignores require a reason;
exact exceptions are stale-checked so obsolete suppressions do not silently accumulate. Mandatory
compiler correctness cannot be suppressed.
Intentional departures remain explicit. Exact exceptions and path- or resource-scoped ignores
require a reason; exact exceptions are stale-checked so obsolete suppressions do not silently
accumulate. Mandatory compiler correctness cannot be suppressed.

See [Findings and exceptions](/concepts/rules/findings-and-exceptions) for configuration examples.

Expand Down
24 changes: 23 additions & 1 deletion concepts/rules/findings-and-exceptions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ reason = "This example intentionally demonstrates one sampled row."
An exception refers to one exact Rule code and path. If the finding disappears, SQLBuild reports
the stale exception so obsolete configuration does not accumulate silently.

## Path-scoped ignores
## Path- and resource-scoped ignores

Use a path ignore when a documented project area intentionally follows a different convention:

Expand All @@ -34,6 +34,28 @@ reason = "Examples retain intentionally minimal SQL."
Path ignores accept exact codes and family prefixes. Keep their scope narrow and explain why the
project differs from the selected requirement.

Use `selectors` when the exception follows graph-resource identities or lineage rather than files:

```toml
[[rules.rule_ignores]]
rules = ["SQBRSQL021"]
selectors = ["intermediate_*"]
reason = "These intermediate interfaces intentionally preserve upstream columns."
```

Selectors use the same grammar as SQLBuild commands, including exact names, name globs, tags,
resource paths, and graph expansion such as `+intermediate_*`. Use `paths` for authored-file glob
matching, including SQL tests and audits that are not graph resources:

```toml
[[rules.rule_ignores]]
rules = ["SQBRSQL021"]
paths = ["models/**/intermediate_*.sql"]
reason = "These intermediate SQL files intentionally preserve upstream columns."
```

`paths` and `selectors` may be combined in one scoped ignore. Both forms require a reason.

## Mandatory correctness

Mandatory compiler correctness is not configurable and cannot be suppressed. A project must first
Expand Down
17 changes: 15 additions & 2 deletions concepts/selectors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,23 @@ When no `--select` is provided, all models are selected.

### Name

Select a single model by name:
Select a single resource by name:

```bash
sqb build --select fact_orders
```

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

```bash
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:
Expand Down Expand Up @@ -129,10 +140,12 @@ sqb build --select +fact_orders --exclude tag:staging

## Error handling

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

```
unknown selector name 'nonexistent_model'
unknown selector pattern 'missing_*'
no models found under path 'models/nonexistent'.
no models found with tag 'nonexistent_tag'
path selector 'fact_orders~' requires names on both sides of '~'
Expand Down
Loading