dbt-labs / dbt-labs/docs.getdbt.com
Clarify YAML vs Jinja syntax for `full_refresh` “unset” value
- Dominant language
- JavaScript
- Stars
- 215
- Forks
- 1.2k
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 130
Description
### Contributions
- [x] I have read the contribution docs, and understand what's expected of me.
### Link to the page on docs.getdbt.com requiring updates
https://docs.getdbt.com/reference/resource-configs/full_refresh
### What part(s) of the page would you like to see updated?
## Issue summary
The `full_refresh` configuration documentation could be clearer and may cause users to accidentally trigger unwanted full refreshes.
## Areas for improvement in current documentation
### 1. Inconsistent examples vs. behavior table
- Examples show only `false | true`
- Behavior table mentions `none` without explaining the syntax differences between YAML and Jinja
### 2. Critical YAML syntax error
Writing `+full_refresh: none` in YAML creates the string "none", which dbt interprets as truthy, leading to full refreshes on every run rather than the intended behavior (that's what I did)
### 3. Missing "unset" examples
Sometimes it would be beneficial to explicitly show that a model follows the `--full-refresh` flag, but the examples don't currently demonstrate how to do this properly.
## Suggested improvements
### Update YAML examples to include `null`:
```yml
models:
[]:
+full_refresh: false | true | null
```
### Update Jinja examples to include `none`:
```sql
{{ config(
full_refresh = false | true | none
) }}
```
### Clarify the behavior table:
| full_refresh value | Behavior |
| ---------------------------- | -------- |
| If set to true | The resource _always_ performs a full refresh, regardless of whether you pass the --full-refresh flag in the dbt command. |
| If set to false | The resource _never_ performs a full refresh, regardless of whether you pass the --full-refresh flag in the dbt command. |
| If set to `none` (Jinja) / `null` (YAML) / omitted | The resource follows the behavior of the --full-refresh flag. If the flag is used, the resource will perform a full refresh; otherwise, it will not. |
### Additional information
_No response_
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.