revising and condensing definitions (#5067)

Closes #5062

## What are you changing in this pull request and why?

Revising the definitions and then makign a reusable to place them on two
pages.

## Checklist
<!--
Uncomment when publishing docs for a prerelease version of dbt:
- [ ] Add versioning components, as described in [Versioning
Docs](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-entire-pages)
- [ ] Add a note to the prerelease version [Migration
Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/docs/dbt-versions/core-upgrade)
-->
- [ ] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [ ] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [ ] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."

Adding or removing pages (delete if not applicable):
- [ ] Add/remove page in `website/sidebars.js`
- [ ] Provide a unique filename for new pages
- [ ] Add an entry for deleted pages in `website/vercel.json`
- [ ] Run link testing locally with `npm run build` to update the links
that point to deleted pages

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).
+
+
+<VersionBlock firstVersion="1.5" >
+
+<IndirSelect features={'/snippets/indirect-selection-definitions.md'}/>
+
+</VersionBlock>
 
 For example, you can run tests that only refer to selected nodes using a CLI configuration:
 
@@ -49,5 +58,3 @@ flags:
 ```
 
 </File>
-
-

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,64 +58,96 @@ 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).
+:::
 
 </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 
+</VersionBlock>
 
-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. The following illustrates which tests will be run when you execute `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-build.png" width="85%" title="dbt build" />
 
-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-buildable.png" width="85%" title="Buildable"/>
+
+<Lightbox src src="/img/docs/reference/indirect-selection-cautious.png" width="85%" title="Cautious"/>
+
+<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)">
+
+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"
 ```
 
 </TabItem>
 
-<TabItem value="cautious" label="Cautious mode">
+<TabItem value="buildable" label="Buildable 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.
+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
+```
+
+</TabItem>
 
+<TabItem value="cautious" label="Cautious mode">
+
+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
 
 ```
 
 </TabItem>
 
+<TabItem value="empty" label="Empty mode">
+
+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
+
+```
+
+</TabItem>
+
 </Tabs>
 
 </VersionBlock>
 
+<!--Tabs for 1.4 only -->
+
 <VersionBlock firstVersion="1.4" lastVersion="1.4">
 
 <Tabs queryString="indirect-selection-mode">
@@ -167,7 +201,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 +227,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,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).
+