From 81992fd35323871be2339b621e78aed42ce6dc8a Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 12 Dec 2024 15:09:09 +0000 Subject: [PATCH 01/12] add supported examples for alias this pr adds additional examples for the `alias` config for the supported resources. missing examples were for dbt_projct.yml, properties.yml, and sql config block (depending on the resource) Resolves #6512 --- .../docs/reference/resource-configs/alias.md | 112 ++++++++++++++++-- 1 file changed, 102 insertions(+), 10 deletions(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index c14804ef2a7..33e577ec5a4 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -8,9 +8,11 @@ datatype: string -Specify a custom alias for a model in your `dbt_project.yml` file or config block. +Specify a custom alias for a model in your `dbt_project.yml` file, `models/properties.yml` file, or config block in a SQL file. -For example, if you have a model that calculates `sales_total` and want to give it a more user-friendly alias, you can alias it like this: +For example, if you have a model that calculates `sales_total` and want to give it a more user-friendly alias, you can alias it as shown in the following examples. + +In the `dbt_project.yml` file, the following example sets a default `alias` for the `sales_total` model at the project level: @@ -22,16 +24,40 @@ models: ``` +In the `models/properties.yml` file, the following specifies an `alias` as part of the model's metadata, useful for centralized configuration: + + + +```yml +version: 2 + +models: + - name: sales_total + config: + alias: sales_dashboard +``` + + +In `models/sales_total.sql` file, the following assigns the `alias` directly in the model file: + + + +```sql +{{ config( + alias="sales_dashboard" +) }} +``` + + This would return `analytics.finance.sales_dashboard` in the database, instead of the default `analytics.finance.sales_total`. +Configure a seed's alias in your `dbt_project.yml` file or a `properties.yml` file. The following examples demonstrate how to `alias` a seed named `product_categories` to `categories_data`. -Configure a seed's alias in your `dbt_project.yml` file or config block. - -For example, if you have a seed that represents `product_categories` and want to alias it as `categories_data`, you would alias like this: +In the `dbt_project.yml` file at the project level: @@ -41,6 +67,21 @@ seeds: product_categories: +alias: categories_data ``` + + +In the `seeds/properties.yml` file: + + + +```yml +version: 2 + +seeds: + - name: product_categories + config: + alias: categories_data +``` + This would return the name `analytics.finance.categories_data` in the database. @@ -65,7 +106,9 @@ seeds: Configure a snapshots's alias in your `dbt_project.yml` file or config block. -For example, if you have a snapshot that is named `your_snapshot` and want to alias it as `the_best_snapshot`, you would alias like this: +The following examples demonstrate how to `alias` a snapshot named `your_snapshot` to `the_best_snapshot`. + +In the `dbt_project.yml` file at the project level: @@ -75,20 +118,57 @@ snapshots: your_snapshot: +alias: the_best_snapshot ``` + -This would build your snapshot to `analytics.finance.the_best_snapshot` in the database. +In the `snapshots/properties.yml` file: + + +```yml +version: 2 + +snapshots: + - name: your_snapshot + config: + alias: the_best_snapshot +``` + + +In `snapshots/your_snapshot.sql` file: + + + +```sql +{{ config( + alias="the_best_snapshot" +) }} +``` +This would build your snapshot to `analytics.finance.the_best_snapshot` in the database. + -Configure a test's alias in your `schema.yml` file or config block. +Configure a data test's alias in your `dbt_project.yml` file, `properties.yml` file, or config block in the model file. + +The following examples demonstrate how to `alias` a unique data test named `order_id` to `unique_order_id_test` to identify a specific data test. -For example, to add a unique test to the `order_id` column and give it an alias `unique_order_id_test` to identify this specific test, you would alias like this: +In the `dbt_project.yml` file at the project level: - + + +```yml +tests: + your_project: + +alias: unique_order_id_test +``` + + +In the `models/properties.yml` file: + + ```yml models: @@ -99,6 +179,18 @@ models: - unique: alias: unique_order_id_test ``` + + +In `tests/unique_order_id_test.sql` file: + + + +```sql +{{ config( + alias="unique_order_id_test", + severity="error", +``` + When using [`store_failures_as`](/reference/resource-configs/store_failures_as), this would return the name `analytics.finance.orders_order_id_unique_order_id_test` in the database. From 8df1848f2c31fbffb618a80f2cbf3a82dbb10761 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 12 Dec 2024 15:21:24 +0000 Subject: [PATCH 02/12] Update alias.md --- website/docs/reference/resource-configs/alias.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index 33e577ec5a4..66e9e3f1074 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -96,9 +96,6 @@ seeds: +alias: country_mappings ``` - - - From ff4a383b0ff4008b170f9fc6b1dd8b4be1382565 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 12 Dec 2024 15:48:28 +0000 Subject: [PATCH 03/12] Update alias.md --- website/docs/reference/resource-configs/alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index 66e9e3f1074..b568c437fa9 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -191,7 +191,7 @@ In `tests/unique_order_id_test.sql` file: When using [`store_failures_as`](/reference/resource-configs/store_failures_as), this would return the name `analytics.finance.orders_order_id_unique_order_id_test` in the database. - + 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 04/12] 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 05/12] 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 21abafadc2891af02abefd795c73c57bdba3a7de Mon Sep 17 00:00:00 2001 From: Doug Beatty <44704949+dbeatty10@users.noreply.github.com> Date: Thu, 12 Dec 2024 17:43:56 -0700 Subject: [PATCH 06/12] `dbt retry` will only work if dbt can parse the project and generate a manifest --- website/docs/docs/deploy/retry-jobs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/docs/deploy/retry-jobs.md b/website/docs/docs/deploy/retry-jobs.md index f439351aec5..4e3ad0d429f 100644 --- a/website/docs/docs/deploy/retry-jobs.md +++ b/website/docs/docs/deploy/retry-jobs.md @@ -10,6 +10,7 @@ If your dbt job run completed with a status of **Error**, you can rerun it from - You have a [dbt Cloud account](https://www.getdbt.com/signup). - You must be using [dbt version](/docs/dbt-versions/upgrade-dbt-version-in-cloud) 1.6 or newer. +- dbt can successfully parse the project and generate a [manifest](/reference/artifacts/manifest-json) - The most recent run of the job hasn't completed successfully. The latest status of the run is **Error**. - The job command that failed in the run must be one that supports the [retry command](/reference/commands/retry). From 56e47da64aaeebc1ffcde068d41cbb7b8c2d16f7 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Dec 2024 09:11:22 +0000 Subject: [PATCH 07/12] Update website/docs/reference/resource-configs/alias.md Co-authored-by: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> --- website/docs/reference/resource-configs/alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index b568c437fa9..dbb772ccee4 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -24,7 +24,7 @@ models: ``` -In the `models/properties.yml` file, the following specifies an `alias` as part of the model's metadata, useful for centralized configuration: +The following specifies an `alias` as part of the `models/properties.yml` file metadata, useful for centralized configuration: From 7af79c48688538f0cf31d0bfd06fbf121d9b8f4a Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Dec 2024 09:11:38 +0000 Subject: [PATCH 08/12] Update website/docs/reference/resource-configs/alias.md Co-authored-by: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> --- website/docs/reference/resource-configs/alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index dbb772ccee4..5beaa238806 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -38,7 +38,7 @@ models: ``` -In `models/sales_total.sql` file, the following assigns the `alias` directly in the model file: +The following assigns the `alias` directly in the In `models/sales_total.sql` file: 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 09/12] 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 10/12] 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 11/12] 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. From 725cf73b9a8c966f958f5e9e361eaee5a6f97e89 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Fri, 13 Dec 2024 10:08:47 +0000 Subject: [PATCH 12/12] Update website/docs/reference/node-selection/syntax.md --- website/docs/reference/node-selection/syntax.md | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index f659e520c31..6af7d01c1c0 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -1,7 +1,6 @@ --- title: "Syntax overview" sidebar_label: "Syntax overview" -pagination_prev: "docs/reference/node-selection/node-selection" --- dbt's node selection syntax makes it possible to run only specific resources in a given invocation of dbt. This selection syntax is used for the following subcommands: