From db85ebb276339224cc25f15c34fd3c1dc673d2d7 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 8 Jan 2025 10:44:54 +0000 Subject: [PATCH 1/8] add unit and data test examples --- .../resource-properties/description.md | 133 +++++++++++++++++- 1 file changed, 131 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index cf7b2b29a5a..7f06172661a 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -14,6 +14,7 @@ description: "This guide explains how to use the description key to add YAML des { label: 'Analyses', value: 'analyses', }, { label: 'Macros', value: 'macros', }, { label: 'Data tests', value: 'data_tests', }, + { label: 'Unit tests', value: 'unit_tests', }, ] }> @@ -150,15 +151,36 @@ macros: +You can add a description to a [singular data test](/docs/build/data-tests#singular-data-tests) or a [generic data test](/docs/build/data-tests#generic-data-tests). + ```yml +# Singular data test example + version: 2 data_tests: - name: data_test_name description: markdown_string +``` + + + + + +```yml +# Generic data test example + +version: 2 +models: + - name: model_name + columns: + - name: column_name + tests: + - unique + description: markdown_string ``` @@ -167,7 +189,45 @@ data_tests: -The `description` property is available for generic and singular data tests beginning in dbt v1.9. +The `description` property is available for generic and singular data tests beginning in dbt v1.8. + + + + + + + + + + + +```yml +unit_tests: + - name: unit_test_name + description: "markdown_string" + model: model_name + given: ts + - input: ref_or_source_call + rows: + - {column_name: column_value} + - {column_name: column_value} + - {column_name: column_value} + - {column_name: column_value} + - input: ref_or_source_call + format: csv + rows: dictionary | string + expect: + format: dict | csv | sql + fixture: fixture_name +``` + + + + + + + +The `description` property is available for [unit tests](/docs/build/unit-tests) beginning in dbt v1.8. @@ -176,13 +236,17 @@ The `description` property is available for generic and singular data tests begi ## Definition -A user-defined description. Can be used to document: + +A user-defined description used to document: + - a model, and model columns - sources, source tables, and source columns - seeds, and seed columns - snapshots, and snapshot columns - analyses, and analysis columns - macros, and macro arguments +- data tests, and data test columns +- unit tests for models These descriptions are used in the documentation website rendered by dbt (refer to [the documentation guide](/docs/build/documentation) or [dbt Explorer](/docs/collaborate/explore-projects)). @@ -400,3 +464,68 @@ models: If mixing images and text, also consider using a docs block. +### Add a description to a data test + +You can add a `description` property to a generic or singular data test. + +#### Generic data test + +This example shows a generic data test that checks for unique values in a column for the `orders` model. + + + +```yaml +version: 2 + +models: + - name: orders + columns: + - name: order_id + tests: + - unique + description: "The order_id is unique for every row in the orders model" +``` + + +#### Singular data test + +This example shows a singular data test that checks to ensure all values in the `payments` model are not negative (≥ 0). + + + +```yaml +version: 2 +data_tests: + - name: assert_total_payment_amount_is_positive + description: > + Refunds have a negative amount, so the total amount should always be >= 0. + Therefore return records where total amount < 0 to make the test fail. + +``` + + +Note that in order for the test to run, the `tests/assert_total_payment_amount_is_positive.sql` SQL file has to exist in the `tests` directory. + +### Add a description to a unit test + +This example shows a unit test that checks to ensure the `opened_at` timestamp is properly truncated to a date for the `stg_locations` model. + + + +```yaml +unit_tests: + - name: test_does_location_opened_at_trunc_to_date + description: "Check that opened_at timestamp is properly truncated to a date." + model: stg_locations + given: + - input: source('ecom', 'raw_stores') + rows: + - {id: 1, name: "Rego Park", tax_rate: 0.2, opened_at: "2016-09-01T00:00:00"} + - {id: 2, name: "Jamaica", tax_rate: 0.1, opened_at: "2079-10-27T23:59:59.9999"} + expect: + rows: + - {location_id: 1, location_name: "Rego Park", tax_rate: 0.2, opened_date: "2016-09-01"} + - {location_id: 2, location_name: "Jamaica", tax_rate: 0.1, opened_date: "2079-10-27"} +``` + + From b8a0dc3f0eeffbccc2a28ce3e4d469a945d03c54 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 8 Jan 2025 10:50:07 +0000 Subject: [PATCH 2/8] add list of examples\ --- .../reference/resource-properties/description.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index 7f06172661a..203fa274ad0 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -260,6 +260,18 @@ Be mindful of YAML semantics when providing a description. If your description c ## Examples +This section contains examples of how to add descriptions to various resources: + +- [Add a simple description to a model and column](#add-a-simple-description-to-a-model-and-column)
+- [Add a multiline description to a model](#add-a-multiline-description-to-a-model)
+- [Use some markdown in a description](#use-some-markdown-in-a-description)
+- [Use a docs block in a description](#use-a-docs-block-in-a-description)
+- [Link to another model in a description](#link-to-another-model-in-a-description) +- [Include an image from your repo in your descriptions](#include-an-image-from-your-repo-in-your-descriptions)
+- [Include an image from the web in your descriptions](#include-an-image-from-the-web-in-your-descriptions)
+- [Add a description to a data test](#add-a-description-to-a-data-test)
+- [Add a description to a unit test](#add-a-description-to-a-unit-test)
+ ### Add a simple description to a model and column From 362ffe4962cdceaeea4ecad6783e80f57b98bf2a Mon Sep 17 00:00:00 2001 From: "Leona B. Campbell" <3880403+runleonarun@users.noreply.github.com> Date: Wed, 8 Jan 2025 11:15:16 -0800 Subject: [PATCH 3/8] Apply suggestions from code review --- website/docs/reference/resource-properties/description.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index 203fa274ad0..b074532a030 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -163,7 +163,6 @@ version: 2 data_tests: - name: data_test_name description: markdown_string -``` @@ -181,7 +180,6 @@ models: tests: - unique description: markdown_string -``` From 44ef1b2c1b0f69183136b51e5d855d652d28b3ba Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 9 Jan 2025 09:58:36 +0000 Subject: [PATCH 4/8] Update website/docs/reference/resource-properties/description.md Co-authored-by: Leona B. Campbell <3880403+runleonarun@users.noreply.github.com> --- website/docs/reference/resource-properties/description.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index b074532a030..175978f8ec0 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -501,7 +501,7 @@ models: This example shows a singular data test that checks to ensure all values in the `payments` model are not negative (≥ 0). - + ```yaml version: 2 From 5ead31a87d817ab563935492fc96c57445646439 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 9 Jan 2025 09:59:42 +0000 Subject: [PATCH 5/8] Update website/docs/reference/resource-properties/description.md Co-authored-by: Leona B. Campbell <3880403+runleonarun@users.noreply.github.com> --- website/docs/reference/resource-properties/description.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index 175978f8ec0..8cfe0b8d5ed 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -187,7 +187,7 @@ models: -The `description` property is available for generic and singular data tests beginning in dbt v1.8. +The `description` property is available for generic and singular data tests beginning in dbt v1.9. From f130f056cba8e687125607e7a5d8c973e8823a11 Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 9 Jan 2025 10:07:25 +0000 Subject: [PATCH 6/8] Update description.md --- .../reference/resource-properties/description.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index 8cfe0b8d5ed..1bc59c4074a 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -163,7 +163,7 @@ version: 2 data_tests: - name: data_test_name description: markdown_string - +``` @@ -180,7 +180,7 @@ models: tests: - unique description: markdown_string - +``` @@ -189,7 +189,7 @@ models: The `description` property is available for generic and singular data tests beginning in dbt v1.9. - + @@ -476,6 +476,15 @@ If mixing images and text, also consider using a docs block. ### Add a description to a data test + + +:::tip +The `description` property is available for generic and singular data tests beginning in dbt v1.9. +::: + + + + You can add a `description` property to a generic or singular data test. #### Generic data test From ad55a197f4233abfb07d0df1ecfab4df72bbd842 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Thu, 9 Jan 2025 10:24:03 +0000 Subject: [PATCH 7/8] add version callout --- .../resource-properties/description.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index 1bc59c4074a..efb560c0fa7 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -187,7 +187,7 @@ models: -The `description` property is available for generic and singular data tests beginning in dbt v1.9. +The `description` property is available for [singular data tests](/docs/build/data-tests#singular-data-tests) or [generic data tests](/docs/build/data-tests#generic-data-tests) beginning in dbt v1.9. @@ -478,14 +478,11 @@ If mixing images and text, also consider using a docs block. -:::tip -The `description` property is available for generic and singular data tests beginning in dbt v1.9. -::: + - + - -You can add a `description` property to a generic or singular data test. +You can add a `description` property to a generic or singular data test. #### Generic data test @@ -527,6 +524,12 @@ Note that in order for the test to run, the `tests/assert_total_payment_amount_i ### Add a description to a unit test + + + + + + This example shows a unit test that checks to ensure the `opened_at` timestamp is properly truncated to a date for the `stg_locations` model. From ff2c6c46264b0bbb06080baff33ecdcfdac6973b Mon Sep 17 00:00:00 2001 From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> Date: Thu, 9 Jan 2025 15:08:47 +0000 Subject: [PATCH 8/8] Update description.md add missing : --- website/docs/reference/resource-properties/description.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index efb560c0fa7..7c182f1794d 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -178,7 +178,7 @@ models: columns: - name: column_name tests: - - unique + - unique: description: markdown_string ``` @@ -498,7 +498,7 @@ models: columns: - name: order_id tests: - - unique + - unique: description: "The order_id is unique for every row in the orders model" ```