From f2048c70253f8a7dd991824e0a122b7c8b1e31d0 Mon Sep 17 00:00:00 2001 From: Doug Beatty <44704949+dbeatty10@users.noreply.github.com> Date: Thu, 12 Dec 2024 17:05:43 -0700 Subject: [PATCH 1/5] Rephrase the two criteria for resolving `ref` calls with the `--defer` flag --- website/docs/reference/node-selection/defer.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/website/docs/reference/node-selection/defer.md b/website/docs/reference/node-selection/defer.md index 863494de12e..0b92485d159 100644 --- a/website/docs/reference/node-selection/defer.md +++ b/website/docs/reference/node-selection/defer.md @@ -29,11 +29,12 @@ dbt test --models [...] --defer --state path/to/artifacts -When the `--defer` flag is provided, dbt will resolve `ref` calls differently depending on two criteria: -1. Is the referenced node included in the model selection criteria of the current run? -2. Does the referenced node exist as a database object in the current environment? +By default, dbt uses the [`target`](/reference/dbt-jinja-functions/target) namespace to resolve `ref` calls. -If the answer to both is **no**—a node is not included _and_ it does not exist as a database object in the current environment—references to it will use the other namespace instead, provided by the state manifest. +But with `--defer`, dbt will use the state manifest instead if the following criteria are met: + +1. The node isn’t in the selected nodes **and** +2. It doesn’t exist in the database (or `--favor-state` is used). Ephemeral models are never deferred, since they serve as "passthroughs" for other `ref` calls. @@ -46,7 +47,7 @@ Deferral requires both `--defer` and `--state` to be set, either by passing flag #### Favor state -You can optionally skip the second criterion by passing the `--favor-state` flag. If passed, dbt will favor using the node defined in your `--state` namespace, even if the node exists in the current target. +You can optionally skip the second criterion by passing the `--favor-state` flag. If passed, dbt will favor using the node defined in your `--state` namespace, even if the node exists in the current target. Selected nodes will still resolve via the `target` namespace, regardless of the `--favor-state` flag. ### Example From 7b7946437e010779e6f485589ecb6d4fa702fa96 Mon Sep 17 00:00:00 2001 From: Doug Beatty <44704949+dbeatty10@users.noreply.github.com> Date: Thu, 12 Dec 2024 17:31:02 -0700 Subject: [PATCH 2/5] Simply the explanation for `--favor-state` --- website/docs/reference/node-selection/defer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/defer.md b/website/docs/reference/node-selection/defer.md index 0b92485d159..13b966dd3a9 100644 --- a/website/docs/reference/node-selection/defer.md +++ b/website/docs/reference/node-selection/defer.md @@ -47,7 +47,7 @@ Deferral requires both `--defer` and `--state` to be set, either by passing flag #### Favor state -You can optionally skip the second criterion by passing the `--favor-state` flag. If passed, dbt will favor using the node defined in your `--state` namespace, even if the node exists in the current target. Selected nodes will still resolve via the `target` namespace, regardless of the `--favor-state` flag. +If `--favor-state` is passed, dbt will favor the node definition from the `--state` directory, _unless_ that node is also included among the selected nodes. ### Example From 71ab4c50912a339b29a32d8be7bd1b0ec0094df1 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Dec 2024 09:54:11 +0000 Subject: [PATCH 3/5] Update website/docs/reference/node-selection/defer.md --- website/docs/reference/node-selection/defer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/defer.md b/website/docs/reference/node-selection/defer.md index 13b966dd3a9..82aeb272699 100644 --- a/website/docs/reference/node-selection/defer.md +++ b/website/docs/reference/node-selection/defer.md @@ -31,7 +31,7 @@ dbt test --models [...] --defer --state path/to/artifacts By default, dbt uses the [`target`](/reference/dbt-jinja-functions/target) namespace to resolve `ref` calls. -But with `--defer`, dbt will use the state manifest instead if the following criteria are met: +When `--defer` is enabled, dbt resolves ref calls using the state manifest instead, but only if: 1. The node isn’t in the selected nodes **and** 2. It doesn’t exist in the database (or `--favor-state` is used). From badbdeb8e9eda633ab00c8cfcdf854f56ff235a0 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Dec 2024 09:55:23 +0000 Subject: [PATCH 4/5] Update website/docs/reference/node-selection/defer.md --- website/docs/reference/node-selection/defer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/defer.md b/website/docs/reference/node-selection/defer.md index 82aeb272699..10b5e3490e0 100644 --- a/website/docs/reference/node-selection/defer.md +++ b/website/docs/reference/node-selection/defer.md @@ -47,7 +47,7 @@ Deferral requires both `--defer` and `--state` to be set, either by passing flag #### Favor state -If `--favor-state` is passed, dbt will favor the node definition from the `--state` directory, _unless_ that node is also included among the selected nodes. +When `--favor-state` is passed, dbt prioritizes node definitions from the `--state directory`. However, this doesn’t apply if the node is also part of the selected nodes. ### Example From 852f8f1bc510b76476191559ebe4a7ad5dd772f0 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Dec 2024 09:55:49 +0000 Subject: [PATCH 5/5] Update website/docs/reference/node-selection/defer.md --- website/docs/reference/node-selection/defer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/defer.md b/website/docs/reference/node-selection/defer.md index 10b5e3490e0..eddb1ece9d4 100644 --- a/website/docs/reference/node-selection/defer.md +++ b/website/docs/reference/node-selection/defer.md @@ -33,7 +33,7 @@ By default, dbt uses the [`target`](/reference/dbt-jinja-functions/target) names When `--defer` is enabled, dbt resolves ref calls using the state manifest instead, but only if: -1. The node isn’t in the selected nodes **and** +1. The node isn’t among the selected nodes, _and_ 2. It doesn’t exist in the database (or `--favor-state` is used). Ephemeral models are never deferred, since they serve as "passthroughs" for other `ref` calls.