From 8478decb525eff7f6d383527adc37c019509c7e6 Mon Sep 17 00:00:00 2001 From: Will Sargent <109557847+will-sargent-dbtlabs@users.noreply.github.com> Date: Thu, 11 Apr 2024 08:41:23 -0600 Subject: [PATCH 1/8] Adds ls troubleshooting tips --- website/docs/reference/node-selection/syntax.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index 61b53ea5ebd..c7179c25936 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -106,6 +106,19 @@ Note that when you're using `--selector`, most other flags (namely `--select` an +### Troubleshooting tip: Use the `ls` command! + +Constructing and debugging selection logic can be challenging. One of the best ways to get a "preview" of what will be selected is to use the [ls](/reference/commands/list) command. This command, when combined with your selection syntax, will output a list of the nodes that meet that selection criteria. All of the selection syntax argument types are supported. + +Examples: + +```bash +dbt ls --select "path.to.my.models" +dbt ls --select "source_status:fresher+" +dbt ls --select state:modified+ +dbt ls --select "result:+ state:modified+ --defer --state ./" +``` + ## Stateful selection One of the greatest underlying assumptions about dbt is that its operations should be **stateless** and ****. That is, it doesn't matter how many times a model has been run before, or if it has ever been run before. It doesn't matter if you run it once or a thousand times. Given the same raw data, you can expect the same transformed result. A given run of dbt doesn't need to "know" about _any other_ run; it just needs to know about the code in the project and the objects in your database as they exist _right now_. From b9d6499ed64454c05cb6351fe75e5eaa8d5b89be Mon Sep 17 00:00:00 2001 From: Will Sargent <109557847+will-sargent-dbtlabs@users.noreply.github.com> Date: Thu, 11 Apr 2024 09:42:24 -0600 Subject: [PATCH 2/8] Update website/docs/reference/node-selection/syntax.md Co-authored-by: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> --- 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 c7179c25936..f1aca09a7e4 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -106,7 +106,6 @@ Note that when you're using `--selector`, most other flags (namely `--select` an -### Troubleshooting tip: Use the `ls` command! Constructing and debugging selection logic can be challenging. One of the best ways to get a "preview" of what will be selected is to use the [ls](/reference/commands/list) command. This command, when combined with your selection syntax, will output a list of the nodes that meet that selection criteria. All of the selection syntax argument types are supported. From f58e454c965528a3175adcb9d3accf205ee4ef76 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 11 Apr 2024 16:53:24 +0100 Subject: [PATCH 3/8] Update syntax.md --- .../docs/reference/node-selection/syntax.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index f1aca09a7e4..499f1142a94 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -103,21 +103,21 @@ As your selection logic gets more complex, and becomes unwieldly to type out as consider using a [yaml selector](/reference/node-selection/yaml-selectors). You can use a predefined definition with the `--selector` flag. Note that when you're using `--selector`, most other flags (namely `--select` and `--exclude`) will be ignored. - - - +### Troubleshoot with the `ls` command -Constructing and debugging selection logic can be challenging. One of the best ways to get a "preview" of what will be selected is to use the [ls](/reference/commands/list) command. This command, when combined with your selection syntax, will output a list of the nodes that meet that selection criteria. All of the selection syntax argument types are supported. - -Examples: +Constructing and debugging your selection syntax can be challenging. To get a "preview" of what will be selected, we recommend using the [`list` command](/reference/commands/list). This command, when combined with your selection syntax, will output a list of the nodes that meet that selection criteria. The `dbt ls` command supports all types of selection syntax arguments, for example: ```bash -dbt ls --select "path.to.my.models" -dbt ls --select "source_status:fresher+" -dbt ls --select state:modified+ -dbt ls --select "result:+ state:modified+ --defer --state ./" +dbt ls --select "path.to.my.models" # Lists all models in a specific directory. +dbt ls --select "source_status:fresher+" # Shows sources updated since the last dbt source freshness run. +dbt ls --select state:modified+ # Displays nodes modified in comparison to a previous state. +dbt ls --select "result:+ state:modified+ --defer --state ./" # Lists nodes that match certain result statuses and are modified, which can help with troubleshooting. ``` + + + + ## Stateful selection One of the greatest underlying assumptions about dbt is that its operations should be **stateless** and ****. That is, it doesn't matter how many times a model has been run before, or if it has ever been run before. It doesn't matter if you run it once or a thousand times. Given the same raw data, you can expect the same transformed result. A given run of dbt doesn't need to "know" about _any other_ run; it just needs to know about the code in the project and the objects in your database as they exist _right now_. From 5d089ec28f31f163a64451f56eacad5c50ecb33f Mon Sep 17 00:00:00 2001 From: Will Sargent <109557847+will-sargent-dbtlabs@users.noreply.github.com> Date: Thu, 11 Apr 2024 09:59:09 -0600 Subject: [PATCH 4/8] Update website/docs/reference/node-selection/syntax.md Co-authored-by: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> --- website/docs/reference/node-selection/syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index 499f1142a94..4d39a91c12e 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -108,7 +108,7 @@ Note that when you're using `--selector`, most other flags (namely `--select` an Constructing and debugging your selection syntax can be challenging. To get a "preview" of what will be selected, we recommend using the [`list` command](/reference/commands/list). This command, when combined with your selection syntax, will output a list of the nodes that meet that selection criteria. The `dbt ls` command supports all types of selection syntax arguments, for example: ```bash -dbt ls --select "path.to.my.models" # Lists all models in a specific directory. +dbt ls --select "path/to/my/models" # Lists all models in a specific directory. dbt ls --select "source_status:fresher+" # Shows sources updated since the last dbt source freshness run. dbt ls --select state:modified+ # Displays nodes modified in comparison to a previous state. dbt ls --select "result:+ state:modified+ --defer --state ./" # Lists nodes that match certain result statuses and are modified, which can help with troubleshooting. From 604d8706ebc579dff591ff199e83bee9d686967a Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 11 Apr 2024 16:59:40 +0100 Subject: [PATCH 5/8] Update syntax.md --- website/docs/reference/node-selection/syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index 4d39a91c12e..4cd16cf77dd 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -58,7 +58,7 @@ Examples: ```bash dbt run --select "my_dbt_project_name" # runs all models in your project dbt run --select "my_dbt_model" # runs a specific model -dbt run --select "path.to.my.models" # runs all models in a specific directory +dbt run --select "path/to/my/models" # runs all models in a specific directory dbt run --select "my_package.some_model" # run a specific model in a specific package dbt run --select "tag:nightly" # run models with the "nightly" tag dbt run --select "path/to/models" # run models contained in path/to/models From 69596fca9f5d66e560d42de7d43033cacbe3478a Mon Sep 17 00:00:00 2001 From: Will Sargent <109557847+will-sargent-dbtlabs@users.noreply.github.com> Date: Thu, 11 Apr 2024 10:08:34 -0600 Subject: [PATCH 6/8] Tweaks the result:table --- website/docs/reference/node-selection/syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index 4cd16cf77dd..e9d68baf41b 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -191,7 +191,7 @@ dbt run --select "result: --defer --state path/to/prod/artifacts" The available options depend on the resource (node) type: -| | model | seed | snapshot | test | +| result:\ | model | seed | snapshot | test | |----------------|-------|------|------|----------| | `result:error` | ✅ | ✅ | ✅ | ✅ | | `result:success` | ✅ | ✅ | ✅ | | From 8c111fac804d524229bd800380f82129a1f840fc Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 11 Apr 2024 17:09:48 +0100 Subject: [PATCH 7/8] Update website/docs/reference/node-selection/syntax.md --- website/docs/reference/node-selection/syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index e9d68baf41b..dfa024739a4 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -111,7 +111,7 @@ Constructing and debugging your selection syntax can be challenging. To get a " dbt ls --select "path/to/my/models" # Lists all models in a specific directory. dbt ls --select "source_status:fresher+" # Shows sources updated since the last dbt source freshness run. dbt ls --select state:modified+ # Displays nodes modified in comparison to a previous state. -dbt ls --select "result:+ state:modified+ --defer --state ./" # Lists nodes that match certain result statuses and are modified, which can help with troubleshooting. +dbt ls --select "result:+ state:modified+ --defer --state ./" # Lists nodes that match certain [result statuses](/reference/node-selection/syntax#the-result-status) and are modified. ``` From a139818d8c33856fe6fb364fe8a8f2a63d5cadb9 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 11 Apr 2024 17:20:52 +0100 Subject: [PATCH 8/8] Update syntax.md --- website/docs/reference/node-selection/syntax.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/docs/reference/node-selection/syntax.md b/website/docs/reference/node-selection/syntax.md index dfa024739a4..ed0b563731d 100644 --- a/website/docs/reference/node-selection/syntax.md +++ b/website/docs/reference/node-selection/syntax.md @@ -191,14 +191,14 @@ dbt run --select "result: --defer --state path/to/prod/artifacts" The available options depend on the resource (node) type: -| result:\ | model | seed | snapshot | test | +| `result:\` | model | seed | snapshot | test | |----------------|-------|------|------|----------| -| `result:error` | ✅ | ✅ | ✅ | ✅ | -| `result:success` | ✅ | ✅ | ✅ | | -| `result:skipped` | ✅ | | ✅ | ✅ | -| `result:fail` | | | | ✅ | -| `result:warn` | | | | ✅ | -| `result:pass` | | | | ✅ | +| `result:error` | ✅ | ✅ | ✅ | ✅ | +| `result:success` | ✅ | ✅ | ✅ | | +| `result:skipped` | ✅ | | ✅ | ✅ | +| `result:fail` | | | | ✅ | +| `result:warn` | | | | ✅ | +| `result:pass` | | | | ✅ | ### Combining `state` and `result` selectors