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

Docs for saving and using state artifacts

Open
#4,917 0 comments 0 reactions 0 assignees View on GitHub
content dbt Core 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.

### 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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.