revising and condensing definitions

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:
@@ -14,6 +16,8 @@ When all flags are set, the order of precedence is as follows. Refer to [About g
 
 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).
 
+<IndirSelect features={'/snippets/indirect-selection-definitions.md'}/>
+
 For example, you can run tests that only refer to selected nodes using a CLI configuration:
 
 <File name='Usage'>

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
@@ -60,32 +62,38 @@ The "buildable" and "cautious" modes can be useful in environments when you're o
 
 </VersionBlock>
 
-<VersionBlock firstVersion="1.5" >
 
-These are the modes to configure the behavior when performing indirect selection (with `eager` as the default):
+<IndirSelect features={'/snippets/indirect-selection-definitions.md'}/>
 
-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.
+<!--tabs for eager mode, cautious mode, empty, and buildable mode -->
+<!--Tabs for 1.5+ -->
 
-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
 
-</VersionBlock>
+<VersionBlock firstVersion="1.5">
 
-<!--tabs for eager mode, cautious mode, and buildable mode -->
+To visualize these methods, suppose you have `model_a`, `model_b`, and `model_c` and associated data tests. Here's what it will look like when you execute `dbt run` vs. `dbt build` with the various indirect selection modes:
 
-<VersionBlock lastVersion="1.3">
+<DocCarousel slidesPerView={1}>
 
-<Tabs queryString="indirect-selection-mode">
-<TabItem value="eager" label="Eager mode (default)">
+<Lightbox src src="/img/docs/reference/indirect-selection-dbt-run.png" width="85%" title="dbt run"/>
 
-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.
+<Lightbox src src="/img/docs/reference/indirect-selection-eager.png" width="85%" title="Eager (default)"/>
 
-In this mode, any test that depends on unbuilt resources will raise an error.
+<Lightbox src src="/img/docs/reference/indirect-selection-cautious.png" width="85%" title="Cautious"/>
+
+<Lightbox src src="/img/docs/reference/indirect-selection-buildable.png" width="85%" title="Buildable"/>
+
+<Lightbox src src="/img/docs/reference/indirect-selection-empty.png" width="85%" title="Empty"/>
+
+</DocCarousel>
 
+<Tabs queryString="indirect-selection-mode">
+<TabItem value="eager" label="Eager mode (default)">
+
+For example, during the build process, any model that depends on the selected "orders" model or its dependent models will be built. Tests that refer to the selected "order" model or its dependent models will be executed during the testing process:
+
 ```shell
 dbt test --select "orders"
 dbt build --select "orders"
@@ -95,16 +103,36 @@ dbt build --select "orders"
 
 <TabItem value="cautious" label="Cautious mode">
 
-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.
+For example, only the "orders" model (or node) and its dependent models will be selected for testing or building:
 
-It will only include tests whose references are each within the selected nodes.
+```shell
+dbt test --select "orders" --indirect-selection=cautious
+dbt build --select "orders" --indirect-selection=cautious
+
+```
+
+</TabItem>
+
+<TabItem value="buildable" label="Buildable mode">
+
+For example, dbt runs tests that reference "orders" within the selected nodes (or their ancestors).
 
-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
+```
 
-dbt test --select "orders" --indirect-selection=cautious
-dbt build --select "orders" --indirect-selection=cautious
+</TabItem>
+
+<TabItem value="empty" label="Empty mode">
+
+This mode 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
 
 ```
 
@@ -114,6 +142,8 @@ dbt build --select "orders" --indirect-selection=cautious
 
 </VersionBlock>
 
+<!--Tabs for 1.4 only -->
+
 <VersionBlock firstVersion="1.4" lastVersion="1.4">
 
 <Tabs queryString="indirect-selection-mode">
@@ -167,7 +197,8 @@ dbt build --select "orders" --indirect-selection=buildable
 
 </VersionBlock>
 
-<VersionBlock firstVersion="1.5">
+<!--Tabs for 1.3 and lower only -->
+<VersionBlock lastVersion="1.3">
 
 <Tabs queryString="indirect-selection-mode">
 <TabItem value="eager" label="Eager mode (default)">
@@ -192,48 +223,21 @@ 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
 
 ```
 
 </TabItem>
 
-<TabItem value="buildable" label="Buildable mode">
-
-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
-```
-
-</TabItem>
-
-<TabItem value="empty" label="Empty mode">
-
-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
-
-```
-
-</TabItem>
-
 </Tabs>
 
 </VersionBlock>
 
 <!--End of tabs for eager mode, cautious mode, buildable mode, and empty mode -->
 
-### Syntax examples
+### Test selection syntax examples
 
 Setting `indirect_selection` can also be specified in a [yaml selector](/reference/node-selection/yaml-selectors#indirect-selection).
 

website/snippets/_indirect-selection-definitions.md

@@ -0,0 +1,23 @@
+<VersionBlock firstVersion="1.5" >
+
+You can use the following modes to configure the behavior when performing indirect selection (with `eager` as the default). Test exclusion is always greedy: if ANY parent is explicitly excluded, the test will be excluded as well.
+
+The `buildable` and `cautious` can be useful in environments when you're only building a subset of your DAG, and you want to avoid the test failures you'd see in `eager` mode caused by unbuilt resources. You can also achieve this with [deferral](/reference/node-selection/defer).
+
+#### Eager mode (default)
+
+By default, runs tests if any of their 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, helping to identify potential issues.
+
+#### 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 parents nodes are unselected and, consequently, unbuilt.
+
+#### Buildable mode
+
+Only runs tests that refer to selected nodes (or their ancestors). Only builds models that rely on the 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.
+
+#### Empty mode
+
+Restricts the build to only the selected node and ignores any indirect dependencies, including tests. It does not execute any tests, whether they are directly attached to the selected node or not. The empty mode is typically used for interactive compilation without running any tests.
+
+</VersionBlock>