Skip to content

Commit

Permalink
Splitting up global configs into pages (#3332)
Browse files Browse the repository at this point in the history
## What are you changing in this pull request and why?
The `global-configs` reference guide had become a single page of
increasing size. This breaks it down into individual pages which will
make the content a little easier to find, especially when using the
search functions.

Most of the features in the original one-shot get their own page but
some gather multiple sections into a single page. Specifically:
`print-output`
`logs`
`parsing`

## Checklist
Uncomment if you're publishing docs for a prerelease version of dbt
(delete if not applicable):
- [x] 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)

- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
and [About
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
so my content adheres to these guidelines.
- [x] 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 new pages (delete if not applicable):
- [x] Add page to `website/sidebars.js`
- [x] Provide a unique filename for the new page

Removing or renaming existing pages (delete if not applicable):
- [x] Remove page from `website/sidebars.js`
- [x] Add an entry `website/static/_redirects`
- [x] [Ran link
testing](https://github.com/dbt-labs/docs.getdbt.com#running-the-cypress-tests-locally)
to update the links that point to the deleted page
  • Loading branch information
matthewshaver authored Jun 1, 2023
2 parents 15357d7 + 23a23aa commit 3d73eb7
Show file tree
Hide file tree
Showing 34 changed files with 681 additions and 604 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ tags: [Feb-2023]

You can now use the `--no-partial-parse` flag to disable partial parsing in your dbt Cloud job commands. 

Previously, the [`--no-partial-parse` global config](/reference/global-configs#partial-parsing) was only available in dbt Core. For more information, refer to [partial parsing](/reference/parsing#partial-parsing).
Previously, the [`--no-partial-parse` global config](/reference/global-configs/parsing) was only available in dbt Core. For more information, refer to [partial parsing](/reference/parsing#partial-parsing).
4 changes: 2 additions & 2 deletions website/docs/docs/deploy/job-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,12 @@ Job command failures can mean different things for different commands. Some comm

- **Failure at`dbt run`** — [`dbt run`](/reference/commands/run) executes compiled SQL model files against the current target database. It will fail if there is an error in any of the built models. Tests on upstream resources prevent downstream resources from running and a failed test will skip them.

- **Failure at `dbt test`** — [`dbt test`](/reference/commands/test) runs tests defined on models, sources, snapshots, and seeds. A test can pass, fail, or warn depending on its [severity](reference/resource-configs/severity). Unless you set [warnings as errors](/reference/global-configs#warnings-as-errors), only an error stops the next step.
- **Failure at `dbt test`** — [`dbt test`](/reference/commands/test) runs tests defined on models, sources, snapshots, and seeds. A test can pass, fail, or warn depending on its [severity](reference/resource-configs/severity). Unless you set [warnings as errors](/reference/global-configs/warnings), only an error stops the next step.

- **Failure at `dbt build`** — [`dbt build`](/reference/commands/build) runs models, tests, snapshots, and seeds. This command executes resources in the DAG-specified order. If any upstream resource fails, all downstream resources are skipped, and the command exits with an error code of 1.

- **Selector failures**
- If a [`select`](/reference/node-selection/set-operators) matches multiple nodes and one of the nodes fails, then the job will have an exit code `1` and the subsequent command will fail. If you specified the [`—fail-fast`](/reference/global-configs#failing-fast) flag, then the first failure will stop the entire connection for any models that are in progress.
- If a [`select`](/reference/node-selection/set-operators) matches multiple nodes and one of the nodes fails, then the job will have an exit code `1` and the subsequent command will fail. If you specified the [`—fail-fast`](/reference/global-configs/failing-fast) flag, then the first failure will stop the entire connection for any models that are in progress.

- If a selector doesn't match any nodes, it's not considered a failure.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ tests/functional/test_example.py .X [100%]

You can find more ways to run tests, along with a full command reference, in the [pytest usage docs](https://docs.pytest.org/how-to/usage.html).

We've found the `-s` flag (or `--capture=no`) helpful to print logs from the underlying dbt invocations, and to step into an interactive debugger if you've added one. You can also use environment variables to set [global dbt configs](/reference/global-configs), such as `DBT_DEBUG` (to show debug-level logs).
We've found the `-s` flag (or `--capture=no`) helpful to print logs from the underlying dbt invocations, and to step into an interactive debugger if you've added one. You can also use environment variables to set [global dbt configs](/reference/global-configs/about-global-configs), such as `DBT_DEBUG` (to show debug-level logs).

## Testing your adapter

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,4 +98,4 @@ Run `dbt --help` to see new & improved help documentation :)
- The [`version: 2` top-level key](/reference/project-configs/version) is now **optional** in all YAML files. Also, the [`config-version: 2`](/reference/project-configs/config-version) and `version:` top-level keys are now optional in `dbt_project.yml` files.
- [Events and logging](/reference/events-logging): Added `node_relation` (`database`, `schema`, `identifier`) to the `node_info` dictionary, available on node-specific events
- Support setting `--project-dir` via environment variable: [`DBT_PROJECT_DIR`](/reference/dbt_project.yml)
- More granular [configurations](/reference/global-configs) for logging (to set log format, log levels, and colorization) and cache population
- More granular [configurations](/reference/global-configs/about-global-configs) for logging (to set log format, log levels, and colorization) and cache population
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ For more detailed information and to ask any questions, please visit [dbt-core/d
- **dbt-Jinja context:** The [local_md5](/reference/dbt-jinja-functions/local_md5) context method will calculate an [MD5 hash](https://en.wikipedia.org/wiki/MD5) for use _within_ dbt. (Not to be confused with SQL md5!)
- [**Exposures**](/docs/build/exposures) can now depend on `metrics`.
- [**"Tarball" packages**](/docs/build/packages#internally-hosted-tarball-URL): Some organizations have security requirements to pull resources only from internal services. To address the need to install packages from hosted environments (such as Artifactory or cloud storage buckets), it's possible to specify any accessible URL where a compressed dbt package can be downloaded.
- [**Granular "warn error" configuration**](/reference/global-configs#warnings-as-errors): Thanks to a full cleanup and consolidation of warning and exception classes within `dbt-core`, it is now possible to define a more granular `--warn-error-options` configuration that specifies the exact warnings you do (or don't) want dbt to treat as errors.
- [**Granular "warn error" configuration**](/reference/global-configs/warnings): Thanks to a full cleanup and consolidation of warning and exception classes within `dbt-core`, it is now possible to define a more granular `--warn-error-options` configuration that specifies the exact warnings you do (or don't) want dbt to treat as errors.
- [**Deferral**](/reference/node-selection/defer#favor-state) supports an optional configuration, `--favor-state`.

### Advanced configurations for incremental models
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ See GitHub discussion [dbt-labs/dbt-core#5468](https://github.com/dbt-labs/dbt-c
- **[Metrics](/docs/build/metrics)** now support an `expression` type (metrics-on-metrics), as well as a `metric()` function to use when referencing metrics from within models, macros, or `expression`-type metrics. For more information on how to use expression metrics, check out the [**`dbt_metrics` package**](https://github.com/dbt-labs/dbt_metrics)
- **[dbt-Jinja functions](/reference/dbt-jinja-functions)** now include the [`itertools` Python module](/reference/dbt-jinja-functions/modules#itertools), as well as the [set](/reference/dbt-jinja-functions/set) and [zip](/reference/dbt-jinja-functions/zip) functions.
- **[Node selection](/reference/node-selection/syntax)** includes a [file selection method](/reference/node-selection/methods#the-file-method) (`-s model.sql`), and [yaml selector](/reference/node-selection/yaml-selectors) inheritance.
- **[Global configs](/reference/global-configs)** now include CLI flag and environment variable settings for [`target-path`](/reference/project-configs/target-path) and [`log-path`](/reference/project-configs/log-path), which can be used to override the values set in `dbt_project.yml`
- **[Global configs](/reference/global-configs/about-global-configs)** now include CLI flag and environment variable settings for [`target-path`](/reference/project-configs/target-path) and [`log-path`](/reference/project-configs/log-path), which can be used to override the values set in `dbt_project.yml`

### Specific adapters

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Expected a schema version of "https://schemas.getdbt.com/dbt/manifest/v5.json" i
- [`print`](/reference/dbt-jinja-functions/print) exposes the Python `print()` function. It can be used as an alternative to `log()`, and together with the `QUIET` config, for advanced macro-driven workflows.
- [`selected_resources`](/reference/dbt-jinja-functions/selected_resources) exposes, at runtime, the list of DAG nodes selected by the current task.

[**Global configs**](/reference/global-configs) include some new additions:
[**Global configs**](/reference/global-configs/about-global-configs) include some new additions:

- `QUIET` and `NO_PRINT`, to control which log messages dbt prints to terminal output. For use in advanced macro-driven workflows, such as [codegen](https://hub.getdbt.com/dbt-labs/codegen/latest/).
- `CACHE_SELECTED_ONLY` is an _experimental_ config that can significantly speed up dbt's start-of-run preparations, in cases where you're running only a few models from a large project that manages many schemas.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ Several under-the-hood changes from past minor versions, tagged with deprecation
- Add [metrics](/docs/build/metrics), a new node type
- [Generic tests](/guides/best-practices/writing-custom-generic-tests) can be defined in `tests/generic` (new), in addition to `macros/` (as before)
- [Parsing](/reference/parsing): partial parsing and static parsing have been turned on by default.
- [Global configs](/reference/global-configs) have been standardized. Related updates to [global CLI flags](/reference/global-cli-flags) and [`profiles.yml`](/reference/profiles.yml).
- [Global configs](/reference/global-configs/about-global-configs) have been standardized. Related updates to [global CLI flags](/reference/global-cli-flags) and [`profiles.yml`](/reference/profiles.yml).
- [The `init` command](/reference/commands/init) has a whole new look and feel. It's no longer just for first-time users.
- Add `result:<status>` subselectors for smarter reruns when dbt models have errors and tests fail. See examples: [Pro-tips for Workflows](/guides/legacy/best-practices#pro-tips-for-workflows)
- Secret-prefixed [env vars](/reference/dbt-jinja-functions/env_var) are now allowed only in `profiles.yml` + `packages.yml`
2 changes: 1 addition & 1 deletion website/docs/reference/commands/debug.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar_label: "debug"
id: "debug"
---

`dbt debug` is a utility function to test the database connection and show information for debugging purposes. Not to be confused with [debug-level logging](/reference/global-configs#debug-level-logging) via the `--debug` option which increases verbosity.
`dbt debug` is a utility function to test the database connection and show information for debugging purposes. Not to be confused with [debug-level logging](/reference/global-configs/about-global-configs#debug-level-logging) via the `--debug` option which increases verbosity.

The `--config-dir` option to `dbt debug` will show the configured location for the `profiles.yml` file and exit:

Expand Down
12 changes: 6 additions & 6 deletions website/docs/reference/commands/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,30 +73,30 @@ For more information on running parents or children of specific models, see the

<Changelog>

- Moved to [global configs](/reference/global-configs) in v1.0
- Moved to [global configs](/reference/global-configs/about-global-configs) in v1.0

</Changelog>

See [global configs](/reference/global-configs#failing-fast)
See [global configs](/reference/global-configs/failing-fast)

## Failing fast

<Changelog>

- The `--fail-fast` flag is new in dbt v0.17.0
- Moved to [global configs](/reference/global-configs) in v1.0
- Moved to [global configs](/reference/global-configs/about-global-configs) in v1.0

</Changelog>

See [global configs](/reference/global-configs#failing-fast)
See [global configs](/reference/global-configs/failing-fast)

## Enable or Disable Colorized Logs

<Changelog>

- The `--use-colors` and `--no-use-colors` flags are new in dbt v0.18.0
- Moved to [global configs](/reference/global-configs) in v1.0
- Moved to [global configs](/reference/global-configs/about-global-configs) in v1.0

</Changelog>

See [global configs](/reference/global-configs#use-colors)
See [global configs](/reference/global-configs/print-output#print-color)
2 changes: 1 addition & 1 deletion website/docs/reference/dbt-jinja-functions/print.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: "Use the `print()` to print messages to the log file and stdout."

Use the `print()` function when you want to print messages to both the log file and standard output (stdout).

When used in conjunction with the `QUIET` global config, which suppresses non-error logs, you will only see error logs and the print messages in stdout. For more information, see [Global configs](/reference/global-configs).
When used in conjunction with the `QUIET` global config, which suppresses non-error logs, you will only see error logs and the print messages in stdout. For more information, see [Global configs](/reference/global-configs/about-global-configs).

## Example

Expand Down
2 changes: 1 addition & 1 deletion website/docs/reference/events-logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Many events are fired while compiling or running a specific DAG node (model, see

<VersionBlock lastVersion="1.3">

When `json` [log formatting](/reference/global-configs#log-formatting) is enabled, dbt will output produce rich, structured log information which can be piped into monitoring tools for analysis, or to power applications with dbt metadata in real time.
When `json` [log formatting](/reference/global-configs/logs) is enabled, dbt will output produce rich, structured log information which can be piped into monitoring tools for analysis, or to power applications with dbt metadata in real time.

Each log line will have the following <Term id="json" /> properties:

Expand Down
2 changes: 1 addition & 1 deletion website/docs/reference/global-cli-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ id: "global-cli-flags"

dbt commands, such as `run` or `test`, support their own command-specific CLI flags. In addition, the dbt command itself supports "global" flags applicable to *all* subcommands.

As of v1.0, the vast majority of global CLI flags map to [global configs](/reference/global-configs), which can also be configured via environment variables or in the `profiles.yml`.
As of v1.0, the vast majority of global CLI flags map to [global configs](/reference/global-configs/about-global-configs), which can also be configured via environment variables or in the `profiles.yml`.

The `--version` and `--record-timing-info` flags remain available to the CLI only.

Expand Down
Loading

0 comments on commit 3d73eb7

Please sign in to comment.