To start using Elementary, you need to add our dbt package to your dbt project.
**Note:** elementary dbt package has to be installed in all of the connected projects in your environment. A dbt package is additional Jinja and SQL code that is added to your project, for additional functionality. In fact, each package is a dbt project. By adding a package to your project, you are adding the package code to be part of your project, you can reference its macros, execute its models, and so on.Add packages to your project by creating a packages.yml file under the main project directory (where your dbt_project.yml is), and adding the relevant package. After you add a new package, run dbt deps to actually pull its code to your project. This is also how you update packages.
Some packages we recommend you check out: dbt_utils, dbt_date, codegen.
<iframe
src="https://www.loom.com/embed/5cf1aaa0708f43a993f8a2945473c7ac"
frameborder="0"
webkitAllowFullscreen
mozAllowFullScreen
allowFullScreen
style={{
position: "absolute",
top: 0,
left: 0,
width: "100%",
height: "100%",
}}
></iframe>
Add the following to your `packages.yml` file (if missing, create it where `dbt_project.yml` is):
```yml packages.yml
packages:
- package: elementary-data/elementary
version: 0.23.0
## Docs: https://docs.elementary-data.com
```
<Accordion title="Important: Materialization config">
For elementary to work, it needs to create some of the models as incremental tables.
Make sure that there are no global materialization configurations that affect elementary, such as:
```yml dbt_project.yml
materialized: "{{ 'table' if target.name == 'prod-cloud' else 'view' }}"
```
Make sure to place the 'elementary' configuration under the models key, and other configs under your project name.
Example:
```yml dbt_project.yml
models:
my_project:
materialized: "{{ 'table' if target.name == 'prod-cloud' else 'view' }}"
elementary:
+schema: "elementary"
```
**If you change materialization settings, make sure to run `dbt run -s elementary --full-refresh`.**
</Accordion>
<Accordion title="Important: Allowing Elementary to override dbt's default test materializations (relevant from dbt 1.8)">
In order for these features to work, add the following file: elementary_materialization.sql to your macros folder so it will look like this:
`macros/elementary_materialization.sql`
In the file copy and paste the following code:
If you use Snowflake:
```
{% materialization test, adapter='snowflake' %}
{{ return(elementary.materialization_test_snowflake()) }}
{% endmaterialization %}
```
If you use any other DWH:
```
{% materialization test, default %}
{{ return(elementary.materialization_test_default()) }}
{% endmaterialization %}
```
</Accordion>
```yml dbt_project.yml
models:
## see docs: https://docs.elementary-data.com/
elementary:
## elementary models will be created in the schema '<your_schema>_elementary'
+schema: "elementary"
## To disable elementary for dev, uncomment this:
# enabled: "{{ target.name in ['prod','analytics'] }}"
```
```shell Terminal
dbt deps
dbt run --select elementary
```
This will mostly create empty tables, that will be updated with artifacts, metrics and test results in your future dbt executions.
Validate the installation by running some tests:
```shell Terminal
dbt test
```
After you ran your tests, we recommend that you ensure that the results were loaded to `elementary_test_results` table.
Once the elementary dbt package has been installed and configured, your test results, run results and dbt artifacts will be loaded to elementary schema tables.
If you see data in these models you completed the package deployment (Congrats! 🎉).
Updating environment settings can take up to a few minutes.