Skip to content

Commit

Permalink
Merging syntax sections (#5898)
Browse files Browse the repository at this point in the history
## What are you changing in this pull request and why?

Merging two sections. For context see
#5748

Credit to [brunocostalopes](https://github.com/brunocostalopes)

## Checklist
<!--
Uncomment when publishing docs for a prerelease version of dbt:
- [ ] Add versioning components, as described in [Versioning
Docs](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-entire-pages)
- [ ] Add a note to the prerelease version [Migration
Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/docs/dbt-versions/core-upgrade)
-->
- [ ] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [ ] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [ ] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."

Adding or removing pages (delete if not applicable):
- [ ] Add/remove page in `website/sidebars.js`
- [ ] Provide a unique filename for new pages
- [ ] Add an entry for deleted pages in `website/vercel.json`
- [ ] Run link testing locally with `npm run build` to update the links
that point to deleted pages

---------

Co-authored-by: Leona B. Campbell <[email protected]>
  • Loading branch information
matthewshaver and runleonarun authored Aug 7, 2024
1 parent eb176c2 commit 8054b9e
Showing 1 changed file with 5 additions and 22 deletions.
27 changes: 5 additions & 22 deletions website/docs/reference/node-selection/syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,36 +193,19 @@ The state and result selectors can also be combined in a single invocation of db
dbt run --select "result:<status>+" state:modified+ --defer --state ./<dbt-artifact-path>
```

### Fresh rebuilds

Only supported by v1.1 or newer.

When a job is selected, dbt Cloud will surface the artifacts from that job's most recent successful run. dbt will then use those artifacts to determine the set of fresh sources. In your job commands, you can signal to dbt to run and test only on these fresher sources and their children by including the `source_status:fresher+` argument. This requires both previous and current state to have the `sources.json` artifact be available. Or plainly said, both job states need to run `dbt source freshness`.

As example:

```bash
# Command step order
dbt source freshness
dbt build --select "source_status:fresher+"
```


For more example commands, refer to [Pro-tips for workflows](/best-practices/best-practice-workflows#pro-tips-for-workflows).

### The "source_status" status

Only supported by v1.1 or newer.

Another element of job state is the `source_status` of a prior dbt invocation. After executing `dbt source freshness`, for example, dbt creates the `sources.json` artifact which contains execution times and `max_loaded_at` dates for dbt sources. You can read more about `sources.json` on the ['sources'](/reference/artifacts/sources-json) page.

The following dbt commands produce `sources.json` artifacts whose results can be referenced in subsequent dbt invocations:
- `dbt source freshness`
The `dbt source freshness` command produces a `sources.json` artifact whose results can be referenced in subsequent dbt invocations.

When a job is selected, dbt Cloud will surface the artifacts from that job's most recent successful run. dbt will then use those artifacts to determine the set of fresh sources. In your job commands, you can signal dbt to run and test only on the fresher sources and their children by including the `source_status:fresher+` argument. This requires both the previous and current states to have the `sources.json` artifact available. Or plainly said, both job states need to run `dbt source freshness`.

After issuing one of the above commands, you can reference the source freshness results by adding a selector to a subsequent command as follows:
After issuing the `dbt source freshness` command, you can reference the source freshness results by adding a selector to a subsequent command:

```bash
# You can also set the DBT_ARTIFACT_STATE_PATH environment variable instead of the --state flag.
dbt source freshness # must be run again to compare current to previous state
dbt build --select "source_status:fresher+" --state path/to/prod/artifacts
```
For more example commands, refer to [Pro-tips for workflows](/best-practices/best-practice-workflows#pro-tips-for-workflows).

0 comments on commit 8054b9e

Please sign in to comment.