diff --git a/website/docs/reference/global-configs/indirect-selection.md b/website/docs/reference/global-configs/indirect-selection.md
index e543ee1a690..5c3c234b621 100644
--- a/website/docs/reference/global-configs/indirect-selection.md
+++ b/website/docs/reference/global-configs/indirect-selection.md
@@ -4,6 +4,8 @@ id: "indirect-selection"
sidebar: "Indirect selection"
---
+import IndirSelect from '/snippets/_indirect-selection-definitions.md';
+
Use the `--indirect_selection` flag to `dbt test` or `dbt build` to configure which tests to run for the nodes you specify. You can set this as a CLI flag or an environment variable. In dbt Core, you can also configure user configurations in [YAML selectors](/reference/node-selection/yaml-selectors) or in the `flags:` block of `dbt_project.yml`, which sets project-level flags.
When all flags are set, the order of precedence is as follows. Refer to [About global configs](/reference/global-configs/about-global-configs) for more details:
@@ -12,7 +14,14 @@ When all flags are set, the order of precedence is as follows. Refer to [About g
1. Environment variables
1. User configurations
-You can set the flag to: `empty`, `buildable`, `cautious`, or `eager` (default). By default, dbt indirectly selects all tests if they touch any resource you select. Learn more about these options in [Indirect selection in Test selection examples](/reference/node-selection/test-selection-examples?indirect-selection-mode=empty#indirect-selection).
+You can set the flag to: `empty`, `buildable`, `cautious`, or `eager` (default). By default, dbt indirectly selects all tests if they touch any resource you select. Learn more about these options in [Indirect selection in Test selection examples](/reference/node-selection/test-selection-examples?indirect-selection-mode=eager#indirect-selection).
+
+
+
+
+
+
+
For example, you can run tests that only refer to selected nodes using a CLI configuration:
@@ -49,5 +58,3 @@ flags:
```
-
-
diff --git a/website/docs/reference/node-selection/test-selection-examples.md b/website/docs/reference/node-selection/test-selection-examples.md
index feb3898c230..4d1936863e9 100644
--- a/website/docs/reference/node-selection/test-selection-examples.md
+++ b/website/docs/reference/node-selection/test-selection-examples.md
@@ -2,6 +2,8 @@
title: "Test selection examples"
---
+import IndirSelect from '/snippets/_indirect-selection-definitions.md';
+
Test selection works a little differently from other resource selection. This makes it very easy to:
* run tests on a particular model
* run tests on all models in a subdirectory
@@ -56,36 +58,46 @@ There are three modes to configure the behavior when performing indirect selecti
Note that test exclusion is always greedy: if ANY parent is explicitly excluded, the test will be excluded as well.
-The "buildable" and "cautious" modes can be useful in environments when you're only building a subset of your DAG, and you want to avoid test failures in "eager" mode caused by unbuilt resources. (Another way to achieve this is with [deferral](/reference/node-selection/defer)).
+:::tip Building subsets of a DAG
+The `buildable` and `cautious` modes can be useful when you're only building a subset of your DAG, and you want to avoid test failures in `eager` mode caused by unbuilt resources. You can also achieve this with [deferral](/reference/node-selection/defer).
+:::
-These are the modes to configure the behavior when performing indirect selection (with `eager` as the default):
+
-1. `eager` (default) - include ANY test that references the selected nodes
-1. `cautious` - restrict to tests that ONLY refer to selected nodes
-1. `buildable` - restrict to tests that ONLY refer to selected nodes (or their ancestors)
-1. `empty` - restrict to tests that are only for the selected node and ignore all tests from the attached nodes
+
-Note that test exclusion is always greedy: if ANY parent is explicitly excluded, the test will be excluded as well.
+
+
-The "buildable", "cautious", and "empty" modes can be useful in environments when you're only building a subset of your DAG, and you want to avoid test failures in "eager" mode caused by unbuilt resources. (Another way to achieve this is with [deferral](/reference/node-selection/defer)).
+### Indirect selection examples
-
+
-
+To visualize these methods, suppose you have `model_a`, `model_b`, and `model_c` and associated data tests. The following illustrates which tests will be run when you execute `dbt build` with the various indirect selection modes:
-
+
-
-
+
-By default, a test will run when ANY parent is selected; we call this "eager" indirect selection. In this example, that would include any test that references orders, even if it references other models as well.
+
-In this mode, any test that depends on unbuilt resources will raise an error.
+
+
+
+
+
+
+
+
+
+
+In this example, during the build process, any test that depends on the selected "orders" model or its dependent models will be executed, even if it depends other models as well.
+
```shell
dbt test --select "orders"
dbt build --select "orders"
@@ -93,16 +105,23 @@ dbt build --select "orders"
-
+
-It is possible to prevent tests from running if one or more of its parents is unselected (and therefore unbuilt); we call this "cautious" indirect selection.
+In this example, dbt executes tests that reference "orders" within the selected nodes (or their ancestors).
-It will only include tests whose references are each within the selected nodes.
-
-Put another way, it will prevent tests from running if one or more of its parents is unselected.
```shell
+dbt test --select "orders" --indirect-selection=buildable
+dbt build --select "orders" --indirect-selection=buildable
+```
+
+
+
+
+In this example, only tests that depend _exclusively_ on the "orders" model will be executed:
+
+```shell
dbt test --select "orders" --indirect-selection=cautious
dbt build --select "orders" --indirect-selection=cautious
@@ -110,10 +129,25 @@ dbt build --select "orders" --indirect-selection=cautious
+
+
+This mode does not execute any tests, whether they are directly attached to the selected node or not.
+
+```shell
+
+dbt test --select "orders" --indirect-selection=empty
+dbt build --select "orders" --indirect-selection=empty
+
+```
+
+
+
+
+
@@ -167,7 +201,8 @@ dbt build --select "orders" --indirect-selection=buildable
-
+
+
@@ -192,6 +227,7 @@ It will only include tests whose references are each within the selected nodes.
Put another way, it will prevent tests from running if one or more of its parents is unselected.
```shell
+
dbt test --select "orders" --indirect-selection=cautious
dbt build --select "orders" --indirect-selection=cautious
@@ -199,41 +235,13 @@ dbt build --select "orders" --indirect-selection=cautious
-
-
-This mode is similarly conservative like "cautious", but is slightly more inclusive.
-
-It will only include tests whose references are each within the selected nodes (or their ancestors).
-
-This is useful in the same scenarios as "cautious", but also includes when a test depends on a model **and** a direct ancestor of that model (like confirming an aggregation has the same totals as its input).
-
-```shell
-dbt test --select "orders" --indirect-selection=buildable
-dbt build --select "orders" --indirect-selection=buildable
-```
-
-
-
-
-
-This mode will only include tests whose references are each within the selected nodes and will ignore all tests from attached nodes.
-
-```shell
-
-dbt test --select "orders" --indirect-selection=empty
-dbt build --select "orders" --indirect-selection=empty
-
-```
-
-
-
-### Syntax examples
+### Test selection syntax examples
Setting `indirect_selection` can also be specified in a [yaml selector](/reference/node-selection/yaml-selectors#indirect-selection).
diff --git a/website/package-lock.json b/website/package-lock.json
index 864954c3e8d..c04a74dcbf8 100644
--- a/website/package-lock.json
+++ b/website/package-lock.json
@@ -8767,9 +8767,9 @@
}
},
"node_modules/caniuse-lite": {
- "version": "1.0.30001470",
- "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001470.tgz",
- "integrity": "sha512-065uNwY6QtHCBOExzbV6m236DDhYCCtPmQUCoQtwkVqzud8v5QPidoMr6CoMkC2nfp6nksjttqWQRRh75LqUmA==",
+ "version": "1.0.30001597",
+ "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001597.tgz",
+ "integrity": "sha512-7LjJvmQU6Sj7bL0j5b5WY/3n7utXUJvAe1lxhsHDbLmwX9mdL86Yjtr+5SRCyf8qME4M7pU2hswj0FpyBVCv9w==",
"funding": [
{
"type": "opencollective",
@@ -8778,6 +8778,10 @@
{
"type": "tidelift",
"url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+ },
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/ai"
}
]
},
@@ -32104,9 +32108,9 @@
}
},
"caniuse-lite": {
- "version": "1.0.30001470",
- "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001470.tgz",
- "integrity": "sha512-065uNwY6QtHCBOExzbV6m236DDhYCCtPmQUCoQtwkVqzud8v5QPidoMr6CoMkC2nfp6nksjttqWQRRh75LqUmA=="
+ "version": "1.0.30001597",
+ "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001597.tgz",
+ "integrity": "sha512-7LjJvmQU6Sj7bL0j5b5WY/3n7utXUJvAe1lxhsHDbLmwX9mdL86Yjtr+5SRCyf8qME4M7pU2hswj0FpyBVCv9w=="
},
"canvas-confetti": {
"version": "1.9.2",
diff --git a/website/snippets/_indirect-selection-definitions.md b/website/snippets/_indirect-selection-definitions.md
new file mode 100644
index 00000000000..92cc57129e9
--- /dev/null
+++ b/website/snippets/_indirect-selection-definitions.md
@@ -0,0 +1,24 @@
+You can use the following modes to configure the behavior when performing indirect selection (with `eager` mode as the default). Test exclusion is always greedy: if ANY parent is explicitly excluded, the test will be excluded as well.
+
+:::tip Building subsets of a DAG
+The `buildable` and `cautious` modes can be useful when you're only building a subset of your DAG, and you want to avoid test failures in `eager` mode caused by unbuilt resources. You can also achieve this with [deferral](/reference/node-selection/defer).
+:::
+
+
+
+#### Eager mode
+
+By default, runs tests if any of the parent nodes are selected, regardless of whether all dependencies are met. This includes ANY tests that reference the selected nodes. Models will be built if they depend on the selected model. In this mode, any tests depending on unbuilt resources will raise an error.
+
+#### Buildable mode
+
+Only runs tests that refer to selected nodes (or their ancestors). This mode is slightly more inclusive than `cautious` by including tests whose references are each within the selected nodes (or their ancestors). This mode is useful when a test depends on a model _and_ a direct ancestor of that model, like confirming an aggregation has the same totals as its input.
+
+#### Cautious mode
+
+Ensures that tests are executed and models are built only when all necessary dependencies of the selected models are met. Restricts tests to only those that exclusively reference selected nodes. Tests will only be executed if all the nodes they depend on are selected, which prevents tests from running if one or more of its parent nodes are unselected and, consequently, unbuilt.
+
+#### Empty mode
+
+Restricts the build to only the selected node and ignores any indirect dependencies, including tests. It doesn't execute any tests, whether they are directly attached to the selected node or not. The empty mode does not include any tests and is automatically used for [interactive compilation](/reference/commands/compile#interactive-compile).
+
diff --git a/website/static/img/docs/reference/indirect-selection-buildable.png b/website/static/img/docs/reference/indirect-selection-buildable.png
new file mode 100644
index 00000000000..4c5119a330b
Binary files /dev/null and b/website/static/img/docs/reference/indirect-selection-buildable.png differ
diff --git a/website/static/img/docs/reference/indirect-selection-cautious.png b/website/static/img/docs/reference/indirect-selection-cautious.png
new file mode 100644
index 00000000000..2a42ff70310
Binary files /dev/null and b/website/static/img/docs/reference/indirect-selection-cautious.png differ
diff --git a/website/static/img/docs/reference/indirect-selection-dbt-build.png b/website/static/img/docs/reference/indirect-selection-dbt-build.png
new file mode 100644
index 00000000000..0b72348b90f
Binary files /dev/null and b/website/static/img/docs/reference/indirect-selection-dbt-build.png differ
diff --git a/website/static/img/docs/reference/indirect-selection-eager.png b/website/static/img/docs/reference/indirect-selection-eager.png
new file mode 100644
index 00000000000..7aef99e1197
Binary files /dev/null and b/website/static/img/docs/reference/indirect-selection-eager.png differ
diff --git a/website/static/img/docs/reference/indirect-selection-empty.png b/website/static/img/docs/reference/indirect-selection-empty.png
new file mode 100644
index 00000000000..1f0e8953419
Binary files /dev/null and b/website/static/img/docs/reference/indirect-selection-empty.png differ