dbt-labs / dbt-labs/docs.getdbt.com

Clarify YAML vs Jinja syntax for `full_refresh` “unset” value

Open
#7,708 0 comments 0 reactions 1 assignee Claimed by @luna-bianca View on GitHub
content improvement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.