diff --git a/docs/guides/add-exposure-tests.mdx b/docs/guides/add-exposure-tests.mdx new file mode 100644 index 000000000..7203d3798 --- /dev/null +++ b/docs/guides/add-exposure-tests.mdx @@ -0,0 +1,94 @@ +--- +title: "Add exposure validation tests" +--- + +After you [install the dbt package](/quickstart#install-the-dbt-package), you can add Elementary exposure validation tests. + +## Exposure validation dbt tests + +Elementary dbt package includes **exposure validation tests, implemented as [dbt tests](https://docs.getdbt.com/docs/building-a-dbt-project/tests)**. +These tests can detect missing columns and column data types for defined exposures. + +## Configure your elementary exposure validation tests + + + You can read up about exposures and how to add them at [the dbt docs + site](https://docs.getdbt.com/docs/build/exposures) + + +Within your `models` directory, add a file called `exposures.yml` + +```yml +exposures: + - name: customers + label: Customer Dashboard + type: dashboard + maturity: high + url: https://your.bi.tool/dashboards/1 + description: > + Shows customer growth + + depends_on: + - ref('customers') + + owner: + name: Callum McData + email: data@jaffleshop.com + meta: + columns: + - name: "customer_id" +``` + +You can optionally also specify the column data type (`data_type`) + +```yml +- name: returned_orders + label: Returned Orders + type: dashboard + maturity: high + url: https://your.bi.tool/dashboards/2 + description: > + Returned orders over time + + depends_on: + - ref('returned_orders') + + owner: + name: Callum McData + email: data@jaffleshop.com + meta: + columns: + - name: "order_id" + data_type: "numeric" +``` + +Then in your module schema, add the elementary exposure tests: + +```yml + ... + - name: returned_orders + description: This table contains all of the returned orders + config: + tags: ["finance"] + + tests: + - elementary.volume_anomalies: + tags: ["table_anomalies"] + timestamp_column: "order_date" + - exposure_schema_validity: + tags: [elementary] + +``` + +We recommend adding a tag to the tests so you could execute these in a dedicated run using the selection parameter `--select tag:elementary`. + +Upon running the tests, if any issues will arise, you'll see your tests fail and in the test result query you'll be able to see the reasons: + +```sql +SELECT 'customers' as exposure, 'https://your.bi.tool/dashboards/1' as url, 'different data type for the column customer_id numeric vs numeric' as error +UNION ALL SELECT 'customers' as exposure, 'https://your.bi.tool/dashboards/1' as url, 'order_id column missing in the model' as error +``` + +## What does it mean when a test fails? + +When a test fail, it means that an exposure is potentially broken, open the your BI tool to validate, and if needed update the `exposures.yml` or your model's schema. diff --git a/docs/mint.json b/docs/mint.json index 698e5f04e..93fd43324 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -98,6 +98,7 @@ }, "guides/add-elementary-tests", "guides/add-schema-tests", + "guides/add-exposure-tests", "guides/python-tests" ] },