Repository: dbt-labs/docs.getdbt.com
Pull request #7120: Docs for dbt-databricks v1.10.0
Author: login: benc-db
Labels: name: content
description: Improvements or additions to content
name: size: medium
description: This change will take up to a week to address
Created: 2025-03-31T16:59:43Z | Merged: 2025-04-09T10:41:11Z

## What are you changing in this pull request and why?
<!--
Describe your changes and why you're making them. If related to an open issue or a pull request on dbt Core or another repository, then link to them here! 

To learn more about the writing conventions used in the dbt Labs docs, see the [Content style guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md).
-->

Adding documentation for v1.10.0 changes in dbt-databricks

## Checklist
- [x] The changes in this PR meet the [docs style guide/fundamentals](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md) required for all content.
- [x] Applied the proper versioning rules if the content is for specific dbt version(s): ([version a whole page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version) or [version a block of content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content)
- [ ] The content in this PR requires a dbt release note, so I added one to the [release notes page](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes).).
<!--
PRE-RELEASE VERSION OF dbt (if so, uncomment):
- [ ] 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)
-->


Diff:
diff --git a/website/docs/reference/global-configs/databricks-changes.md b/website/docs/reference/global-configs/databricks-changes.md
index ca24b822ae5..b3ce72136b4 100644
--- a/website/docs/reference/global-configs/databricks-changes.md
+++ b/website/docs/reference/global-configs/databricks-changes.md
@@ -8,19 +8,173 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag may become default behavior in the future, depending on how `information_schema` changes.
 
-### Use user's folder for Python model notebooks
+:::tip Do I need this flag?
+
+If your complex type comes from processing JSON using `from_json`, you have an alternative: use [`parse_json` to create the column as the `variant` type](https://docs.databricks.com/aws/en/sql/language-manual/functions/parse_json).
+Depending on how you intend to query or further process the data, the `variant` type might be a reasonable alternative in terms of performance, while not suffering from the issue of type truncation in metadata queries.
+
+:::
+
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+When set to `True`, `dbt-databricks ` uses the updated logic for all model types (views, tables, incremental, seeds). It also enables additional, optional config options for more fine-tuned control:
+* `view_update_via_alter` &mdash; When enabled, this config attempts to update the view in place using alter view, instead of using create or replace to replace it.
+* `use_safer_relation_operation` &mdash; When enabled (and if `view_update_via_alter` isn't set), this config makes dbt model updates more safe by staging relations and using rename operations to ensure the live version of the table or view is not disrupted by failures.
+
+These configs aren't required to receive the core benefits of this flag &mdash; like better performance and column/constraint functionality &mdash; but they are gated behind the flag because they introduce more significant changes to how materializations behave.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+With the `use_materialization_v2` flag set to `True`, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+* `view_update_via_alter` &mdash; Updates the view in place using alter view, instead of using create or replace to replace it. This allows continuity of history for the view, keeps the metadata, and helps with Unity Catalog compatibility. Here's an example of how to configure this:
+
+ <File name="schema.yml">
+ 
+ ```yaml
+ version: 2
+  
+ models:
+   - name: market_summary
+     config:
+       materialized: view
+       view_update_via_alter: true
+     
+     columns:
+       - name: country
+         tests:
+           - unique
+           - not_null
+ ...
+ ```
+ 
+ </File>
+
+:::caution There is currently no support for altering the comment on a view via Databricks SQL.
+
+As such, we must replace the view whenever you change its description
+
+:::
+
+* `use_safer_relation_operations` &mdash; When enabled (and if `view_update_via_alter` isn't set), this config makes dbt model updates more safe by creating a new relation in a staging location, swapping it with the existing relation, and deleting the old relation afterward. The following example shows how to configure this:
+
+ <File name="schema.yml">
+ 
+ ```yaml
+ version: 2
+  
+ models:
+   - name: market_summary
+     config:
+       materialized: view
+       use_safer_relation_operations: true
+     
+     columns:
+       - name: country
+         tests:
+           - unique
+           - not_null
+ ...
+ ```
+ 
+ </File>
+
+:::caution This configuration option may increase costs and disrupt Unity Catalog history.
+
+While this approach is equivalent to the default dbt view materialization, it will create additional UC objects, as compared to alternatives.
+Since this config does not use atomic 'create or replace...' for any materialization, the history of the object in Unity Catalog may not behave as you expect.
+Consider carefully before using this model config broadly.
+
+:::
+
+### Changes to the Table materialization
+
+:::caution This flag may increase storage costs for tables.
+
+As with views, these materialization changes could increase costs.
+More temporary objects are used, consistent with other dbt adapters' materializations.
+We consider these changes experimental in part because we do not have enough data quantifying the price impact of this change.
+The benefits though are improvements in performance, safety, and unblocking features that cannot be delivered with the existing materialization.
+
+:::
+
+When `use_materialization_v2` is set to `True`, all materialization paths are updated. The key change is that table creation is separated from inserting rows into the table. This separation greatly improves performance for setting table comments, since adding comments at create time is faster than using separate `alter table` statements. It also resolves compatibility issues in Databricks, where creating and inserting in one step prevents setting comments.
+
+Additionally, this change makes it possible to support other column features &mdash; like column-level masks &mdash; that aren’t compatible with inserting data during creation. While these features aren’t included in version 1.10.0, they can now be added in future releases.
+
+#### Constraints
+
+For several feature releases now, dbt-databricks supported both dbt's [constraint](/reference/resource-properties/constraints) implementation and our own alternative, earlier version called `persist_constraints`. With the `use_materialization_v2` flag, we're beginning to deprecate `persist_constraints` and shifting fully to dbt's native constraint support.
+
+One new enhancement is support for the `expression` field on primary and foreign keys, which lets you pass additional Databricks options &mdash; like using [`RELY` to tell the Databricks optimizer that it may exploit the constraint to rewrite queries](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-ddl-create-table-constraint).
+
+Separating `create` and `insert` also changes how constraints behave. Previously, we would create a table with data and then apply constraints. If the new data violated a constraint, the run would fail &mdash; but by then, it had already replaced the valid table from the previous run.
+
+As with views, you can select between performance and safety with the `use_safer_relation_operations` flag, but regardless of setting, the new materialization approach ensures constraint violations don't make it into the target table.
+
+#### `use_safer_relation_operations`
+
+When using this model configuration with tables, we first create a staging table. After successfully inserting data into the table, we rename it to replace the target materialization. Since Databricks doesn’t support rollbacks, this is a safer approach &mdash; if something fails before the rename, the original table stays intact. That gives you time to troubleshoot without worrying that exposures or work streams relying on that table are broken in the mean time.
+
+If this config is set to `false` (the default), the target table will still never contain constraint-violating data, but it might end up empty if the insert fails due to the constraint. The key difference is whether we replace the target directly or use a staging-and-rename approach.
+
+:::caution This configuration option may increase costs and disrupt Unity Catalog history.
+
+As with views, there is a cost to using additional temporary objects, in the form of creating more UC objects with their own history.
+Consider carefully whether you need this behavior.
+
+:::
+
+### Changes to the Incremental materialization
+
+All the changes made to the [Table materialization section](#changes-to-the-table-materialization) also apply to Incremental materializations.
+
+We’ve also added a new config: `incremental_apply_config_changes`. 
+
+This config lets you control whether dbt should apply changes to things like `tags`, `tblproperties`, and comments during incremental runs. Many users wanted the capability to configure table metadata in Databricks &mdash; like AI-generated comments &mdash; without dbt overwriting them. Previously, dbt-databricks always applied detected changes during incremental runs.
+
+With the V2 materialization, you can now set `incremental_apply_config_changes` to `False` to stop that behavior. (It defaults to `True` to match the previous behavior.)
+
+The following example shows how to configure this:
+
+<File name="schema.yml">
+
+```yaml
+version: 2
+ 
+models:
+  - name: incremental_market_updates
+    config:
+      materialized: incremental
+      incremental_apply_config_changes: false
+...
+```
+
+</File>
diff --git a/website/docs/reference/resource-configs/databricks-configs.md b/website/docs/reference/resource-configs/databricks-configs.md
index 48bb4f7a6cd..5fbf3d0394c 100644
--- a/website/docs/reference/resource-configs/databricks-configs.md
+++ b/website/docs/reference/resource-configs/databricks-configs.md
@@ -59,6 +59,7 @@ dbt-databricks v1.9 adds support for the `table_format: iceberg` config. Try it
 | location_root       | The created table uses the specified directory to store its data. The table alias is appended to it.     | Optional  | SQL, Python     | `/mnt/root`  |
 | partition_by        | Partition the created table by the specified columns. A directory is created for each partition. | Optional   | SQL, Python     | `date_day`  |
 | liquid_clustered_by | Cluster the created table by the specified columns. Clustering method is based on [Delta's Liquid Clustering feature](https://docs.databricks.com/en/delta/clustering.html). Available since dbt-databricks 1.6.2. | Optional          | SQL, Python     | `date_day` |
+| auto_liquid_cluster\+ | The created table is [automatically clustered by Databricks](https://docs.databricks.com/aws/en/delta/clustering#automatic-liquid-clustering).  Available since dbt-databricks 1.10.0 | Optional | SQL, Python | `auto_liquid_cluster: true` |
 | clustered_by        | Each partition in the created table will be split into a fixed number of buckets by the specified columns.      | Optional     | SQL, Python     | `country_code`           |
 | buckets    | The number of buckets to create while clustering   | Required if `clustered_by` is specified   | SQL, Python     | `8`        |
 | tblproperties   | [Tblproperties](https://docs.databricks.com/en/sql/language-manual/sql-ref-syntax-ddl-tblproperties.html) to be set on the created table   | Optional     | SQL, Python*    | `{'this.is.my.key': 12}` |
@@ -71,6 +72,11 @@ dbt-databricks v1.9 adds support for the `table_format: iceberg` config. Try it
 
 ‡ `databricks_tags` are currently only supported at the table level, and applied via `ALTER` statements.
 
+\+ Do not use `liquid_clustered_by` and `auto_liquid_cluster` on the same model.
+
+In dbt-databricks v1.10, there are several new model configurations options gated behind the `use_materialization_v2` flag.
+For full details, see the [documentation of Databricks behavior flags](/docs/reference/global-configs/databricks-changes).
+
 </VersionBlock>
 
 <VersionBlock firstVersion="1.9">


Reviews:
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T19:32:34Z
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T19:34:21Z
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T19:34:47Z
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T19:35:57Z
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T19:37:38Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T21:19:32Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T21:21:29Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T21:25:11Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:22:56Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:25:15Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:26:09Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:26:31Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:26:57Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:27:56Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:38:02Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:54:10Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:54:49Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:55:18Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:55:26Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T18:56:42Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T19:04:45Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T19:06:40Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T19:08:50Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T14:12:14Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T14:13:53Z
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T17:41:29Z
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T17:45:38Z
user: login: amychen1776
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T17:22:29Z
user: login: amychen1776
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T17:34:08Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T17:51:18Z
user: login: benc-db
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-08T18:04:42Z
user: login: mirnawong1
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T10:30:13Z
user: login: mirnawong1
body: thanks so much @benc-db and @amychen1776 for your thoughtful comments and edits - made some small tweaks to shorten the paragraph and fix up some typos of mine too. these are great features and am excited to get this live! 
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-09T10:37:20Z

Review comments:
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: ```suggestion
Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
```

is this what you mean?


created_at: 2025-04-01T19:32:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: does this mean they have to use the flag and also these two model configs below?
created_at: 2025-04-01T19:34:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: the nesting of flags isn't the nicest experience. 🤔 
created_at: 2025-04-01T19:34:47Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: This will be a longstanding flag right? This sounds more like a flag that is more like a global config not a behavior flag?
created_at: 2025-04-01T19:35:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
+:::caution There is currently no support for altering the comment on a view via Databricks SQL.
+
+As such, we must replace the view whenever you change its description
+
+:::
+
+#### `use_safer_relation_operations`
+
+The other new model configuration introduced for views is `use_safer_relation_operations`.
+When this configuration is set to `True`, if `view_update_via_alter` is not set, we will use a multi-step, renaming approach to replacing existing relations.
+Rather than using a `create or replace...` statement to replace an existing view, we create the new view at a staging location, then swap locations with the existing view, before finally deleting the existing view.
+
+:::caution This configuration option may increase storage costs.
+
+While this approach is equivalent to the default dbt view materialization, it will create additional UC objects, as compared to alternatives.
+
+:::
+
+While this setting is more relevant for table and incremental materializations, there are benefits for use with views.
+For example, when replacing a materialized view with a traditional view, we have historically dropped the materialized view prior to creating the new view.
+Although materialized views do not currently support renaming, setting this config ensures that the materialized view is not dropped until we have successfully created the new view in the staging location; as such, there is no longer a scenario where the existing relation is dropped and the new relation fails to be created.
+
+### Changes to the Table materialization
+
+:::caution This flag may increase storage costs for tables.
+
+As with views, these materialization changes could increase costs.
+More temporary objects are used, consistent with other dbt adapters' materializations.
+We consider these changes experimental in part because we do not have enough data quantifying the price impact of this change.
+The benefits though are improvements in performance, safety, and unblocking features that cannot be delivered with the existing materialization.
+
+:::
+
+When `use_materialization_v2` flag is set to `True`, all paths through the materialization are changed.
+The difference that is core to all paths is that we separate table creation from inserting rows into the table.
+This change allows us to significantly improve performance when persisting documentation on the table, as setting comments at create time is much more performant than the alternative (setting the comment on each column as a separate `alter table...` operation), but is not allowed in Databricks when we create and insert data into a table in the same statement.
+Another benefit of this approach is that several other column features, such as column-level masks, are also incompatible with inserting data as part of create.
+While these features are not a part of the 1.10.0 release, they can now be supported in future releases.
+
+#### Constraints
+
+For several feature releases now, dbt-databricks supported both the dbt implementation of constraints and an alternative called `persist_constraints`, that we had implemented prior.
+With the `use_materialization_v2` flag, we begin the deprecation of this alternative implementation, and expand our support for the core dbt implementation.
+We now support the expression field for primary and foreign keys as a way to supply additional Databricks options, such as using [`RELY` to tell the Databricks optimizer that it may exploit the constraint to rewrite queries](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-ddl-create-table-constraint).
+
+Another change to how constraints work in practice is due to separating create and insert.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: ```suggestion
Another change to how constraints work in practice is due to separating out `create` and `insert`.
```
created_at: 2025-04-01T19:37:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: Yes.  There is no 'REPAIR VIEWS' to sync metadata.

Related to this, I learned something very valuable this week and would like your opinion on where/how to handle it in docs.  A lot of times when users have complex column types, its because they are processing json data, say from a production system structured log.  They are using from_json and getting a complex struct/array type out.  This week I recommended a user tryout replacing with parse_json, which gives the variant type back, and voila, no more complex type.  So basically, I'm wondering where/how we should communicate that to users?  Then the problem this flag is trying to solve is avoided.
created_at: 2025-04-01T21:19:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: This is a model config that is gated by the behavior flag above.  This model config requires use_materialization_v2 to be True in order to do anything.  Happy to restructure.  Will answer above comment too.
created_at: 2025-04-01T21:21:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: They don't need to use either of them.  These are new model config options that are opened up if they opt into the new behavior.  Essentially I have one flag that gates experimental materialization rewrites.  When the flag is false, they get materializations that match 1.9.  In the new materializations, there are new options for how to materialize the models.  I'm open to revising this, was just looking to make all of the new materialization behavior opt-in initially, since they are such a fundamental change.
created_at: 2025-04-01T21:25:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -71,6 +72,11 @@ dbt-databricks v1.9 adds support for the `table_format: iceberg` config. Try it
 
 ‡ `databricks_tags` are currently only supported at the table level, and applied via `ALTER` statements.
 
+\+ Do not use `liquid_clustered_by` and `auto_liquid_cluster` on the same model.
+
+In dbt-databricks v1.10, there are several new model configurations options that are gated behind the `use_materialization_v2` flag.
+For full details, see the [documentation of Databricks behavior flags](/docs/reference/global-configs/databricks-changes.md).
path: website/docs/reference/resource-configs/databricks-configs.md
user: login: mirnawong1
body: ```suggestion
For full details, see the [documentation of Databricks behavior flags](/docs/reference/global-configs/databricks-changes).
```
created_at: 2025-04-02T09:22:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,106 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: which additional query do we mean here?
created_at: 2025-04-02T09:25:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,106 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: ```suggestion
| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
```
created_at: 2025-04-02T09:26:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,106 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: ```suggestion
| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
```
created_at: 2025-04-02T09:26:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,106 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: ```suggestion
| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
```
created_at: 2025-04-02T09:26:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: ```suggestion
We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
```
created_at: 2025-04-02T09:27:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: i think it might be helpful here to explicitly state what happens when true. and also introduce how it affects other things like views and seeds
```suggestion
When set to `True`, `dbt-databricks ` uses the updated logic for all model types (views, tables, incremental, seeds) and optionally enables additional config options for more fine-tuned control.

We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
```
created_at: 2025-04-02T09:38:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: i think it'd also be helpful to state the new optional model configs so it transitions into the next sections. so for example:

> When setting the `use_materialization_v2` flag to `True`, it unlocks two optional model configurations for more control over how to handle existing relations:
- `view_update_via_alter` &mdash; When enabled, this config attempts to update the view in place using `alter view`, instead of using `create or replace` to replace it. This allows continuity of history for the view, keeps the metadata, and helps with Unity Catalog compatibility. 
- `use_safer_relation_operations` &mdash; When enabled (and if `view_update_via_alter` isn't set), this config makes dbt update models more safe by creating the new relation in a staging location, swapping it with the existing view, deleting the old relation afterward, and avoids `create or replace...` operations.

You don’t need to use these configs as they’re optional and only relevant when you enable the `use_materialization_v2` flag.
created_at: 2025-04-02T09:54:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
+:::caution There is currently no support for altering the comment on a view via Databricks SQL.
+
+As such, we must replace the view whenever you change its description
+
+:::
+
+#### `use_safer_relation_operations`
+
+The other new model configuration introduced for views is `use_safer_relation_operations`.
+When this configuration is set to `True`, if `view_update_via_alter` is not set, we will use a multi-step, renaming approach to replacing existing relations.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: what happens if you set `view_update_via_alter` as well?
created_at: 2025-04-02T09:54:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: i think for both model configs, it'd be great to have an example of the behavior flag enabled, as well as the model configs enabled so users know how this config looks?
created_at: 2025-04-02T09:55:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
+:::caution There is currently no support for altering the comment on a view via Databricks SQL.
+
+As such, we must replace the view whenever you change its description
+
+:::
+
+#### `use_safer_relation_operations`
+
+The other new model configuration introduced for views is `use_safer_relation_operations`.
+When this configuration is set to `True`, if `view_update_via_alter` is not set, we will use a multi-step, renaming approach to replacing existing relations.
+Rather than using a `create or replace...` statement to replace an existing view, we create the new view at a staging location, then swap locations with the existing view, before finally deleting the existing view.
+
+:::caution This configuration option may increase storage costs.
+
+While this approach is equivalent to the default dbt view materialization, it will create additional UC objects, as compared to alternatives.
+
+:::
+
+While this setting is more relevant for table and incremental materializations, there are benefits for use with views.
+For example, when replacing a materialized view with a traditional view, we have historically dropped the materialized view prior to creating the new view.
+Although materialized views do not currently support renaming, setting this config ensures that the materialized view is not dropped until we have successfully created the new view in the staging location; as such, there is no longer a scenario where the existing relation is dropped and the new relation fails to be created.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: i think for both model configs, it'd be great to have an example of the behavior flag enabled, as well as the model configs enabled so users know how this config looks?
created_at: 2025-04-02T09:55:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
+:::caution There is currently no support for altering the comment on a view via Databricks SQL.
+
+As such, we must replace the view whenever you change its description
+
+:::
+
+#### `use_safer_relation_operations`
+
+The other new model configuration introduced for views is `use_safer_relation_operations`.
+When this configuration is set to `True`, if `view_update_via_alter` is not set, we will use a multi-step, renaming approach to replacing existing relations.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: view_update_via_alter supersedes use_safer_relation_operations if there is a pre-existing view; if there is a pre-existing relation and its not a view, or there is not a pre-existing relation, use_safer_relation_operations can apply (create the view in a staging location, swap out using renames if able).
created_at: 2025-04-02T18:56:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: I guess the question is really, do we think users would want to choose different view behavior on a per-model basis?  As currently implemented, they have that flexibility, but it may not be necessary; having said that, I'm not really sure I understand how to implement global flags that are not behavior flags.
created_at: 2025-04-02T19:04:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,106 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: The 'REPAIR TABLE' command.  And honestly, it really comes down to how Databricks's metadata strategy evolves.  We could end up pivoting depending on whether or not Databricks makes needed improvements to information schema.
created_at: 2025-04-02T19:06:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: Given the other feedback and responses, where would you place the examples?
created_at: 2025-04-02T19:08:49Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: that's a good question @benc-db !  i recommend adding a short “Example” block at the end of each subsection after the model configuration explanation. i think this gives users immediate, relevant context after they’ve learned about the config’s purpose.
created_at: 2025-04-03T14:12:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
+When it does, no further action is taken; otherwise, `alter view...` is used to alter the view in place to match your dbt project.
+This allows continuity of history for the view, which is lost with `create or replace...`, which can fix user-reported issues with Unity Catalog features.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: mirnawong1
body: <img width="767" alt="Screenshot 2025-04-03 at 15 12 28" src="https://github.com/user-attachments/assets/5782ea4b-988d-490e-be53-97eb69221d1e" />
<img width="789" alt="Screenshot 2025-04-03 at 15 12 35" src="https://github.com/user-attachments/assets/dcdb31b3-b034-4294-b5d3-7c17312984a8" />

created_at: 2025-04-03T14:13:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: I see - I was confused about how things were nested in the doc. No need to change the behavior 
created_at: 2025-04-04T17:41:29Z
author_association: CONTRIBUTOR
diff_hunk: @@ -10,17 +10,105 @@ The following are the current [behavior change flags](/docs/reference/global-con
 | ----------------------------- | ----------------------- | -------------------------- |
 | `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
 | `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| `use_materialization_v2`      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
-Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. Furthermore, there is no equivalent option for views at this time.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We currently plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
+### Changes to the Seed materialization
+
+The seeds materialization should have the smallest difference between the old and new materialization, as the primary difference is just removing calls to methods that are not supported by Databricks, such as transaction operations.
+
+### Changes to the View materialization
+
+In conjunction with the flag above, there are two model configuration options that can customize how we handle the view materialization when we detect an existing relation at the target location.
+
+#### `view_update_via_alter`
+
+For view models where we set `view_update_via_alter: True`, when we detect an existing view, rather than using `create or replace...` to replace the existing view, we gather metadata to determine if the existing view matches the dbt project.
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: I can see arguments for both but it would be easier to understand projects with just one behavior. 
I'll just resolve this for now
created_at: 2025-04-04T17:45:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: amychen1776
body: @benc-db  could we make this change?

created_at: 2025-04-08T17:22:29Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: Oh, I think I misinterpreted your feedback the first time, let me take another look
created_at: 2025-04-08T17:51:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -8,19 +8,108 @@ The following are the current [behavior change flags](/docs/reference/global-con
 
 | Flag                          | `dbt-databricks`: Intro | `dbt-databricks`: Maturity |
 | ----------------------------- | ----------------------- | -------------------------- |
-| `use_info_schema_for_columns` | 1.9.0                   | TBD                        |
-| `use_user_folder_for_python`  | 1.9.0                   | TBD                        |
+| [`use_info_schema_for_columns`](#use-information-schema-for-columns) | 1.9.0                   | TBD                        |
+| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)  | 1.9.0                   | TBD                        |
+| [`use_materialization_v2`](#use-restructured-materializations)      | 1.10.0                  | TBD                        |
 
-### Use information schema for columns
+## Use information schema for columns
 
 The `use_info_schema_for_columns` flag is `False` by default.
 
 Setting this flag to `True` will use `information_schema` rather than `describe extended` to get column metadata for Unity Catalog tables. This setting helps you avoid issues where `describe extended` truncates information when the type is a complex struct. However, this setting is not yet the default behavior, as there are performance impacts due to a Databricks metadata limitation because of the need to run `REPAIR TABLE {{relation}} SYNC METADATA` before querying to ensure the `information_schema` is complete. 
+Please note that there is no equivalent option for views at this time which means dbt will still need to use `describe extended` for views.
 
-This flag will become the default behavior when this additional query is no longer needed. 
+This flag will become the default behavior when this additional query is no longer needed.
 
-### Use user's folder for Python model notebooks
+## Use user's folder for Python model notebooks
 
 The `use_user_folder_for_python` flag is `False` by default and results in writing uploaded python model notebooks to `/Shared/dbt_python_models/{{schema}}/`. Setting this flag to `True` will write notebooks to `/Users/{{current user}}/{{catalog}}/{{schema}}/` Writing to the `Shared` folder is deprecated by Databricks as it does not align with governance best practices.
 
-We plan to promote this flag to maturity in v1.10.0.
+We plan to switch the default of this flag to `True` in v1.11.0.
+
+## Use restructured materializations
+
+The `use_materialization_v2` flag is `False` by default and guards significant rewrites of the core materializations in `dbt-databricks` while they are still in an experimental stage.
+
+We plan to switch the default of this flag to `True` in 1.11.0, depending on user feedback.
+
path: website/docs/reference/global-configs/databricks-changes.md
user: login: benc-db
body: Please take another look
created_at: 2025-04-08T18:04:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -71,6 +72,11 @@ dbt-databricks v1.9 adds support for the `table_format: iceberg` config. Try it
 
 ‡ `databricks_tags` are currently only supported at the table level, and applied via `ALTER` statements.
 
+\+ Do not use `liquid_clustered_by` and `auto_liquid_cluster` on the same model.
+
+In dbt-databricks v1.10, there are several new model configurations options that are gated behind the `use_materialization_v2` flag.
path: website/docs/reference/resource-configs/databricks-configs.md
user: login: mirnawong1
body: ```suggestion
In dbt-databricks v1.10, there are several new model configurations options gated behind the `use_materialization_v2` flag.
```
created_at: 2025-04-09T10:30:12Z
author_association: CONTRIBUTOR

PR comments:
user: login: vercel[bot]
created_at: 2025-03-31T16:59:47Z
body: @benc-db is attempting to deploy a commit to the **dbt-labs** Team on [Vercel](https://vercel.com).

A member of the Team first needs to [authorize it](https://vercel.com/git/authorize?team=dbt-labs&type=github&job=%7B%22headInfo%22%3A%7B%22sha%22%3A%22ce9732f76025e02c8cc886243c3d84f807707e91%22%7D%2C%22id%22%3A%22QmesZC7bF3BYJ73FqibCosXpt5vphpm94CwpxRe4Uymg5K%22%2C%22org%22%3A%22dbt-labs%22%2C%22prId%22%3A7120%2C%22repo%22%3A%22docs.getdbt.com%22%7D).


author_association: NONE
user: login: vercel[bot]
created_at: 2025-03-31T18:03:33Z
body: [vc]: #ToMq2DTx3kBeL9ycafvAFx0y+gRY+T+q7q/oEQRQ+ZM=:eyJpc01vbm9yZXBvIjp0cnVlLCJ0eXBlIjoiZ2l0aHViIiwicHJvamVjdHMiOlt7Im5hbWUiOiJkb2NzLWdldGRidC1jb20iLCJyb290RGlyZWN0b3J5Ijoid2Vic2l0ZSIsImluc3BlY3RvclVybCI6Imh0dHBzOi8vdmVyY2VsLmNvbS9kYnQtbGFicy9kb2NzLWdldGRidC1jb20vRTFYU3pxQUFUa0I5MzRrTDdQOTlhOEFNNG1EdCIsInByZXZpZXdVcmwiOiJkb2NzLWdldGRidC1jb20tZ2l0LWZvcmstYmVuYy1kYi1kYXRhYnJpY2tzMTEwMC1kYnQtbGFicy52ZXJjZWwuYXBwIiwibmV4dENvbW1pdFN0YXR1cyI6IkRFUExPWUVEIn1dfQ==
**The latest updates on your projects**. Learn more about [Vercel for Git ↗︎](https://vercel.link/github-learn-more)

| Name | Status | Preview | Updated (UTC) |
| :--- | :----- | :------ | :------ |
| **docs-getdbt-com** | ✅ Ready ([Inspect](https://vercel.com/dbt-labs/docs-getdbt-com/E1XSzqAATkB934kL7P99a8AM4mDt)) | [Visit Preview](https://docs-getdbt-com-git-fork-benc-db-databricks1100-dbt-labs.vercel.app) | Apr 8, 2025 5:18pm |


author_association: NONE
user: login: mirnawong1
created_at: 2025-04-08T14:46:05Z
body: hey @benc-db ! just give us a shout when this pr is ready for re-review 🙏 
author_association: CONTRIBUTOR
user: login: benc-db
created_at: 2025-04-08T17:17:41Z
body: Hi @mirnawong1 ready for re-review, unless you meant that you already re-reviewed it and I need to make more changes before a third review :P
author_association: CONTRIBUTOR
user: login: amychen1776
created_at: 2025-04-08T17:34:51Z
body: I'm approving this from my end (technically) but @mirnawong1 to do the final review and hit merge. 
author_association: CONTRIBUTOR
user: login: mirnawong1
created_at: 2025-04-09T15:34:49Z
body: hey @benc-db @amychen1776  - thanks again and the doc is now live: https://docs.getdbt.com/reference/global-configs/databricks-changes#use-restructured-materializations!
author_association: CONTRIBUTOR