Docs for saving and using state artifacts

[dbeatty10]

Contributions

• 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:

this 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

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 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:

• [CT-3569] [Feature] Add a --favor-state-selector flag that supports node selection syntax dbt-core#9410
• Add results examples to dbt retry page #3625
• [Bug] Inconsistent behaviour of 'defer' with the 'dbt compile' command dbt-core#9991