dbt-labs / dbt-labs/docs.getdbt.com
Docs for saving and using state artifacts
- 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.
### Request
There should be documentation that describes how to:
1. save state artifacts, and
2. use state artifacts.
See below for more detail.
### Link to the page on docs.getdbt.com requiring updates
It seems we'll want two things:
- new page(s)
- cross-linking to pre-existing pages
### What part(s) of the page would you like to see updated?
### Instigating context
From @graciegoheen [here](https://github.com/dbt-labs/docs.getdbt.com/issues/3625#issuecomment-1939244843):
> [this](https://docs.getdbt.com/reference/node-selection/defer) seems to be the only docs for `--state` (the deferral docs) - should we have a separate page for the `--state` flag if it's used by retry and deferral?
### Problem to solve
To save a state artifact, we have this (currently) **non-global** flag:
- [`--target-path`](https://docs.getdbt.com/reference/project-configs/target-path#configuration)
To use that state artifact, we have the these **global** flags:
- `--defer`
- `--state`
- `--defer-state`
- `--favor-state`
### Proposed solution
There should be a page that describes how to:
1. save state artifacts, and
2. use state artifacts.
Since most of these are "global" flags this new page should be similar in style and content to these pages:
- https://docs.getdbt.com/reference/global-configs/logs
- https://docs.getdbt.com/reference/global-configs/cache
- https://docs.getdbt.com/reference/global-configs/failing-fast
- https://docs.getdbt.com/reference/global-configs/json-artifacts
- https://docs.getdbt.com/reference/global-configs/parsing
- https://docs.getdbt.com/reference/global-configs/print-output
- https://docs.getdbt.com/reference/global-configs/usage-stats
- https://docs.getdbt.com/reference/global-configs/version-compatibility
- https://docs.getdbt.com/reference/global-configs/warnings
### Example usage
[Here's](https://github.com/dbt-labs/dbt-core/issues/9410#issuecomment-1912042633) a fancy example of using those flags in combination to make an "n-layer burrito" using ingredients from multiple artifacts.
This is a more complex example than most people will need day-to-day. But it gives at least one example of the flags in combination with each other (including `--target`!)
### Additional information
Related GitHub issues:
- https://github.com/dbt-labs/dbt-core/issues/9410
- https://github.com/dbt-labs/docs.getdbt.com/issues/3625
- https://github.com/dbt-labs/dbt-core/issues/9991
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.