From e0e8309bc879fdc7202f69b25430aa0e19e832e1 Mon Sep 17 00:00:00 2001 From: Doug Beatty Date: Fri, 10 Nov 2023 13:35:10 -0700 Subject: [PATCH 1/6] Update page title --- website/docs/reference/source-properties.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/website/docs/reference/source-properties.md b/website/docs/reference/source-properties.md index d20ef5f2877..d107881967e 100644 --- a/website/docs/reference/source-properties.md +++ b/website/docs/reference/source-properties.md @@ -1,5 +1,5 @@ --- -title: "About source properties" +title: "Source properties" description: "Learn how to use source properties in dbt." --- @@ -8,9 +8,13 @@ description: "Learn how to use source properties in dbt." - [Declaring resource properties](/reference/configs-and-properties) ## Overview -Source properties can be declared in `.yml` files in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)). -You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory. +import PropsCallout from '/snippets/_config-prop-callout.md'; + +Source properties can be declared in any `properties.yml` file in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)).
+ + +You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory: From 26d7cf1fbb3e1b642b5f62264c35527d0cc62dd6 Mon Sep 17 00:00:00 2001 From: Doug Beatty Date: Fri, 10 Nov 2023 14:02:52 -0700 Subject: [PATCH 2/6] Small whitespace and verbiage changes --- website/docs/reference/configs-and-properties.md | 5 ++++- website/docs/reference/dbt_project.yml.md | 3 ++- website/docs/reference/resource-configs/docs.md | 10 ++-------- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/website/docs/reference/configs-and-properties.md b/website/docs/reference/configs-and-properties.md index c2ad5b77629..75c8e1594b1 100644 --- a/website/docs/reference/configs-and-properties.md +++ b/website/docs/reference/configs-and-properties.md @@ -11,7 +11,7 @@ A rule of thumb: properties declare things _about_ your project resources; confi For example, you can use resource **properties** to: * Describe models, snapshots, seed files, and their columns -- Assert "truths" about a model, in the form of [tests](/docs/build/tests), e.g. "this `id` column is unique" +* Assert "truths" about a model, in the form of [tests](/docs/build/tests), e.g. "this `id` column is unique" * Define pointers to existing tables that contain raw data, in the form of [sources](/docs/build/sources), and assert the expected "freshness" of this raw data * Define official downstream uses of your data models, in the form of [exposures](/docs/build/exposures) @@ -67,12 +67,14 @@ Previous versions of the docs referred to these as `schema.yml` files — we've dbt has the ability to define node configs in `.yml` files, in addition to `config()` blocks and `dbt_project.yml`. But the reverse isn't always true: there are some things in `.yml` files that can _only_ be defined there. Certain properties are special, because: + - They have a unique Jinja rendering context - They create new project resources - They don't make sense as hierarchical configuration - They're older properties that haven't yet been redefined as configs These properties are: + - [`description`](/reference/resource-properties/description) - [`tests`](/reference/resource-properties/tests) - [`docs`](/reference/resource-configs/docs) @@ -202,3 +204,4 @@ Runtime Error ``` This error occurred because a semicolon (`;`) was accidentally used instead of a colon (`:`) after the `description` field. To resolve issues like this, find the `.yml` file referenced in the error message and fix any syntax errors present in the file. There are online YAML validators that can be helpful here, but please be mindful of submitting sensitive information to third-party applications! + diff --git a/website/docs/reference/dbt_project.yml.md b/website/docs/reference/dbt_project.yml.md index 9bd85d0d5dd..caf501c27ab 100644 --- a/website/docs/reference/dbt_project.yml.md +++ b/website/docs/reference/dbt_project.yml.md @@ -1,5 +1,5 @@ -Every [dbt project](/docs/build/projects) needs a `dbt_project.yml` file — this is how dbt knows a directory is a dbt project. It also contains important information that tells dbt how to operate on your project. +Every [dbt project](/docs/build/projects) needs a `dbt_project.yml` file — this is how dbt knows a directory is a dbt project. It also contains important information that tells dbt how to operate your project. @@ -96,6 +96,7 @@ vars: + ```yml diff --git a/website/docs/reference/resource-configs/docs.md b/website/docs/reference/resource-configs/docs.md index 0ccd21d7504..d300979a826 100644 --- a/website/docs/reference/resource-configs/docs.md +++ b/website/docs/reference/resource-configs/docs.md @@ -17,10 +17,12 @@ default_value: {show: true} { label: 'Macros', value: 'macros', }, ] }> + + ```yml version: 2 @@ -29,7 +31,6 @@ models: docs: show: true | false node_color: "black" - ``` @@ -53,9 +54,7 @@ seeds: - name: seed_name docs: show: true | false - ``` - @@ -71,9 +70,7 @@ snapshots: - name: snapshot_name docs: show: true | false - ``` - @@ -90,7 +87,6 @@ analyses: docs: show: true | false ``` - @@ -110,9 +106,7 @@ macros: - name: macro_name docs: show: true | false - ``` - Also refer to [macro properties](/reference/macro-properties). From 5863a3d7978aa5b1745ae871541812cff5313f77 Mon Sep 17 00:00:00 2001 From: Doug Beatty Date: Fri, 10 Nov 2023 14:14:05 -0700 Subject: [PATCH 3/6] Revert "Update page title" This reverts commit e0e8309bc879fdc7202f69b25430aa0e19e832e1. --- website/docs/reference/source-properties.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/website/docs/reference/source-properties.md b/website/docs/reference/source-properties.md index d107881967e..d20ef5f2877 100644 --- a/website/docs/reference/source-properties.md +++ b/website/docs/reference/source-properties.md @@ -1,5 +1,5 @@ --- -title: "Source properties" +title: "About source properties" description: "Learn how to use source properties in dbt." --- @@ -8,13 +8,9 @@ description: "Learn how to use source properties in dbt." - [Declaring resource properties](/reference/configs-and-properties) ## Overview +Source properties can be declared in `.yml` files in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)). -import PropsCallout from '/snippets/_config-prop-callout.md'; - -Source properties can be declared in any `properties.yml` file in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)).
- - -You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory: +You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory. From 6431a3a898537fb59127171456f15e8d431db786 Mon Sep 17 00:00:00 2001 From: Doug Beatty Date: Fri, 10 Nov 2023 14:17:27 -0700 Subject: [PATCH 4/6] Update page title --- website/docs/reference/source-properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/source-properties.md b/website/docs/reference/source-properties.md index d20ef5f2877..1fc7a4aef55 100644 --- a/website/docs/reference/source-properties.md +++ b/website/docs/reference/source-properties.md @@ -1,5 +1,5 @@ --- -title: "About source properties" +title: "Source properties" description: "Learn how to use source properties in dbt." --- From 05e744905f411c94e6c9d9abb757cea1d7721c2a Mon Sep 17 00:00:00 2001 From: Doug Beatty Date: Fri, 10 Nov 2023 14:40:14 -0700 Subject: [PATCH 5/6] Remove hyphenation --- website/docs/reference/configs-and-properties.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/configs-and-properties.md b/website/docs/reference/configs-and-properties.md index 75c8e1594b1..8a557c762ed 100644 --- a/website/docs/reference/configs-and-properties.md +++ b/website/docs/reference/configs-and-properties.md @@ -35,11 +35,11 @@ dbt prioritizes configurations in order of specificity, from most specificity to Note - Generic tests work a little differently when it comes to specificity. See [test configs](/reference/test-configs). -Within the project file, configurations are also applied hierarchically. The most-specific config always "wins": In the project file, configurations applied to a `marketing` subdirectory will take precedence over configurations applied to the entire `jaffle_shop` project. To apply a configuration to a model, or directory of models, define the resource path as nested dictionary keys. +Within the project file, configurations are also applied hierarchically. The most specific config always "wins": In the project file, configurations applied to a `marketing` subdirectory will take precedence over configurations applied to the entire `jaffle_shop` project. To apply a configuration to a model, or directory of models, define the resource path as nested dictionary keys. ### Combining configs -Most configurations are "clobbered" when applied hierarchically. Whenever a more-specific value is available, it will completely replace the less-specific value. Note that a few configs have different merge behavior: +Most configurations are "clobbered" when applied hierarchically. Whenever a more specific value is available, it will completely replace the less specific value. Note that a few configs have different merge behavior: - [`tags`](tags) are additive. If a model has some tags configured in `dbt_project.yml`, and more tags applied in its `.sql` file, the final set of tags will include all of them. - [`meta`](/reference/resource-configs/meta) dictionaries are merged (a more specific key-value pair replaces a less specific value with the same key) - [`pre-hook` and `post-hook`](/reference/resource-configs/pre-hook-post-hook) are also additive. From dac137daca30774e38d46580da95479deb5108cd Mon Sep 17 00:00:00 2001 From: Doug Beatty Date: Fri, 10 Nov 2023 15:16:38 -0700 Subject: [PATCH 6/6] Callout snippet for properties and configs --- website/docs/reference/analysis-properties.md | 4 +++- website/docs/reference/exposure-properties.md | 6 +++++- website/docs/reference/macro-properties.md | 7 +++++-- website/docs/reference/source-properties.md | 8 ++++++-- website/snippets/_config-prop-callout.md | 1 + 5 files changed, 20 insertions(+), 6 deletions(-) create mode 100644 website/snippets/_config-prop-callout.md diff --git a/website/docs/reference/analysis-properties.md b/website/docs/reference/analysis-properties.md index fbc7b05538f..880aeddbb0d 100644 --- a/website/docs/reference/analysis-properties.md +++ b/website/docs/reference/analysis-properties.md @@ -2,7 +2,9 @@ title: Analysis properties --- -We recommend you define analysis properties in your `analyses/` directory, which is illustrated in the [`analysis-paths`](/reference/project-configs/analysis-paths) configuration. +import PropsCallout from '/snippets/_config-prop-callout.md'; + +We recommend you define analysis properties in your `analyses/` directory, which is illustrated in the [`analysis-paths`](/reference/project-configs/analysis-paths) configuration.
You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `analyses/` or `models/` directory. diff --git a/website/docs/reference/exposure-properties.md b/website/docs/reference/exposure-properties.md index aaed2a20a09..0bd4cf771af 100644 --- a/website/docs/reference/exposure-properties.md +++ b/website/docs/reference/exposure-properties.md @@ -8,7 +8,11 @@ description: "Read this guide to understand exposure properties in dbt." - [Declaring resource properties](/reference/configs-and-properties) ## Overview -Exposures are defined in `.yml` files nested under an `exposures:` key. You may define `exposures` in YAML files that also define define `sources` or `models`. + +import PropsCallout from '/snippets/_config-prop-callout.md'; + +Exposures are defined in `properties.yml` files nested under an `exposures:` key. You may define `exposures` in YAML files that also define `sources` or `models`.
+ You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory. diff --git a/website/docs/reference/macro-properties.md b/website/docs/reference/macro-properties.md index 9919835f3c5..91a616ded0d 100644 --- a/website/docs/reference/macro-properties.md +++ b/website/docs/reference/macro-properties.md @@ -1,10 +1,13 @@ --- title: Macro properties +id: macro-properties --- -Macro properties can be declared in `.yml` files. +import PropsCallout from '/snippets/_config-prop-callout.md'; -You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders. +Macro properties can be declared in any `properties.yml` file. + +You can name these files `whatever_you_want.yml` and nest them arbitrarily deep in sub-folders. diff --git a/website/docs/reference/source-properties.md b/website/docs/reference/source-properties.md index 1fc7a4aef55..d107881967e 100644 --- a/website/docs/reference/source-properties.md +++ b/website/docs/reference/source-properties.md @@ -8,9 +8,13 @@ description: "Learn how to use source properties in dbt." - [Declaring resource properties](/reference/configs-and-properties) ## Overview -Source properties can be declared in `.yml` files in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)). -You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory. +import PropsCallout from '/snippets/_config-prop-callout.md'; + +Source properties can be declared in any `properties.yml` file in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)).
+ + +You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory: diff --git a/website/snippets/_config-prop-callout.md b/website/snippets/_config-prop-callout.md new file mode 100644 index 00000000000..f21c335734a --- /dev/null +++ b/website/snippets/_config-prop-callout.md @@ -0,0 +1 @@ +{props.title} are "special properties" in that you can't configure them in the dbt_project.yml file or using config() blocks. Refer to Configs and properties for more info.