-
Notifications
You must be signed in to change notification settings - Fork 982
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Break out configuration change monitoring from materialized views (#4610
) ## What are you changing in this pull request and why? Configuration change docs are currently embedded in the materialized view docs and are not intuitively reusable everywhere. This was done because this functionality was first built for materialized views, but it's not necessarily specific to materialized views. ## Checklist - [x] 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). - [x] Update references to this new section for platform specific configs once those PRs are merged Adding new pages (delete if not applicable): - [x] Add page to `website/sidebars.js` - [x] Provide a unique filename for the new page
- Loading branch information
Showing
8 changed files
with
164 additions
and
71 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
86 changes: 86 additions & 0 deletions
86
website/docs/reference/resource-configs/on_configuration_change.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| --- | ||
| resource_types: [models] | ||
| description: "on_configuration_change - Read this in-depth guide to learn about configuration change monitoring in dbt." | ||
| datatype: "string" | ||
| --- | ||
|
|
||
| :::info | ||
| This functionality is currently only supported for [materialized views](/docs/build/materializations#materialized-view) on a subset of adapters. | ||
| ::: | ||
|
|
||
| The `on_configuration_change` config has three settings: | ||
| - `apply` (default) — Attempt to update the existing database object if possible, avoiding a complete rebuild. | ||
| - *Note:* If any individual configuration change requires a full refresh, a full refresh be performed in lieu of individual alter statements. | ||
| - `continue` — Allow runs to continue while also providing a warning that the object was left untouched. | ||
| - *Note:* This could result in downstream failures as those models may depend on these unimplemented changes. | ||
| - `fail` — Force the entire run to fail if a change is detected. | ||
|
|
||
| <Tabs | ||
| groupId="config-languages" | ||
| defaultValue="project-yaml" | ||
| values={[ | ||
| { label: 'Project file', value: 'project-yaml', }, | ||
| { label: 'Property file', value: 'property-yaml', }, | ||
| { label: 'Config block', value: 'config', }, | ||
| ] | ||
| }> | ||
|
|
||
|
|
||
| <TabItem value="project-yaml"> | ||
|
|
||
| <File name='dbt_project.yml'> | ||
|
|
||
| ```yaml | ||
| models: | ||
| [<resource-path>](/reference/resource-configs/resource-path): | ||
| [+](/reference/resource-configs/plus-prefix)[materialized](/reference/resource-configs/materialized): <materialization_name> | ||
| [+](/reference/resource-configs/plus-prefix)on_configuration_change: apply | continue | fail | ||
| ``` | ||
| </File> | ||
| </TabItem> | ||
| <TabItem value="property-yaml"> | ||
| <File name='models/properties.yml'> | ||
| ```yaml | ||
| version: 2 | ||
|
|
||
| models: | ||
| - name: [<model-name>] | ||
| config: | ||
| [materialized](/reference/resource-configs/materialized): <materialization_name> | ||
| on_configuration_change: apply | continue | fail | ||
| ``` | ||
| </File> | ||
| </TabItem> | ||
| <TabItem value="config"> | ||
| <File name='models/<model_name>.sql'> | ||
| ```jinja | ||
| {{ config( | ||
| [materialized](/reference/resource-configs/materialized)="<materialization_name>", | ||
| on_configuration_change="apply" | "continue" | "fail" | ||
| ) }} | ||
| ``` | ||
|
|
||
| </File> | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| Materializations are implemented following this "drop through" life cycle: | ||
| 1. If a model does not exist with the provided path, create the new model. | ||
| 2. If a model exists, but has a different type, drop the existing model and create the new model. | ||
| 3. If `--full-refresh` is supplied, replace the existing model regardless of configuration changes and the `on_configuration_change` setting. | ||
| 4. If there are no configuration changes, perform the default action for that type (e.g. apply refresh for a materialized view). | ||
| 5. Determine whether to apply the configuration changes according to the `on_configuration_change` setting. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.