Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs a for exposure generic tests #1154

Merged
merged 3 commits into from
Sep 28, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ Check out the [contributions guide](https://docs.elementary-data.com/general/con
<a href="https://github.com/NoyaArie"><img src="https://avatars.githubusercontent.com/u/31591071?v=4" width="50" height="50" alt=""/></a>
<a href="https://github.com/ellakz"><img src="https://avatars.githubusercontent.com/u/18530437?v=4" width="50" height="50" alt=""/></a>
<a href="https://github.com/ofek1weiss"><img src="https://avatars.githubusercontent.com/u/55920061?v=4" width="50" height="50" alt=""/></a>
<a href="https://github.com/erikzaadi"><img src="https://avatars.githubusercontent.com/u/77775?v=4" width="50" height="50" alt=""/></a>
<a href="https://github.com/RoiTabach"><img src="https://avatars.githubusercontent.com/u/25003091?v=4" width="50" height="50" alt=""/></a>
<a href="https://github.com/hahnbeelee"><img src="https://avatars.githubusercontent.com/u/55263191?v=4" width="50" height="50" alt=""/></a>
<a href="https://github.com/seanglynn-thrive"><img src="https://avatars.githubusercontent.com/u/93200565?v=4" width="50" height="50" alt=""/></a>
Expand Down
4 changes: 2 additions & 2 deletions docs/_snippets/add-connection-profile.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ Here is a demonstration:
<iframe
src="https://www.loom.com/embed/6eacaed618a746658a3c8e920d1d46b2"
frameborder="0"
webkitallowfullscreen
mozallowfullscreen
webkitAllowFullScreen
mozAllowFullScreen
allowfullscreen
style={{
position: "absolute",
Expand Down
4 changes: 2 additions & 2 deletions docs/_snippets/install-dbt-package.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
<iframe
src="https://www.loom.com/embed/5cf1aaa0708f43a993f8a2945473c7ac"
frameborder="0"
webkitallowfullscreen
mozallowfullscreen
webkitAllowFullScreen
mozAllowFullScreen
allowfullscreen
className="w-full"
style={{ height: "16rem" }}
Expand Down
6 changes: 3 additions & 3 deletions docs/_snippets/quickstart-package-install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ Some packages we recommend you check out: [dbt_utils](https://github.com/dbt-lab
<iframe
src="https://www.loom.com/embed/5cf1aaa0708f43a993f8a2945473c7ac"
frameborder="0"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen
webkitAllowFullscreen
mozAllowFullScreen
allowFullScreen
style={{
position: "absolute",
top: 0,
Expand Down
157 changes: 157 additions & 0 deletions docs/guides/add-exposure-tests.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
---
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 changes in your models' columns that break downstream exposures, such as BI dashboards.

## Configure your elementary exposure validation tests

Within your `models` directory, add a file called `exposures.yml`

```yml
version: 2
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: [email protected]
```

<Tip>
You can read up about exposures and how to add them at [the dbt docs
site](https://docs.getdbt.com/docs/build/exposures)
</Tip>

### Adding the Elementary exposure information

For each exposure wish to be verified, you add a new property called `meta`:

```yml
version: 2
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: [email protected]

meta:
referenced_columns:
- column_name: "customer_id"
```

<Tip>
In the Elementary Cloud, the exposures and exposure validation tests are added
automatically, according to the actual dependency if your BI tool.
</Tip>

You can optionally also specify the column data type (`data_type`)

```yml
version: 2
- 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: [email protected]
meta:
referenced_columns:
- column_name: "order_id"
data_type: "numeric"
```

In addition, if your exposure depends on several nodes, you can depend explicitly per column which source should be tested:

```yml
version: 2
- 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')
- ref('orders')

owner:
name: Callum McData
email: [email protected]
meta:
referenced_columns:
- column_name: "order_id"
data_type: "numeric"
node: ref('returned_orders')
- column_name: "customer_id"
data_type: "numeric"
node: ref('orders')

```

### Adding the Elementary exposure tests for your module

For each module schema you wish to verify the exposure dependencies, 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"
- elementary.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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we have this recommendation in all the test types?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


Upon running the tests, if breaking changes are detected in the model, the test will 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 fails, it means that an exposure is potentially broken due to a missing or wrongly-typed column. Open the your BI tool to validate, and if you make any changes to your dashboards be sure to update the `exposures.yml` and your model schema accordingly.
1 change: 1 addition & 0 deletions docs/mint.json
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@
},
"guides/add-elementary-tests",
"guides/add-schema-tests",
"guides/add-exposure-tests",
"guides/python-tests"
]
},
Expand Down
6 changes: 3 additions & 3 deletions docs/release-notes/releases/0.7.7.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ _April 12, 2023: [v0.7.7 Python](https://github.com/elementary-data/elementary/r
<iframe
src="https://www.loom.com/embed/b92d880b768d44a7bd2b0010a6223b62"
frameborder="0"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen
webkitAllowFullScreen
mozAllowFullScreen
allowFullScreen
style={{
position: "absolute",
top: 0,
Expand Down