diff --git a/website/docs/docs/about-dbt-extension.md b/website/docs/docs/about-dbt-extension.md
index 65d13972fcc..14aff98b7dc 100644
--- a/website/docs/docs/about-dbt-extension.md
+++ b/website/docs/docs/about-dbt-extension.md
@@ -25,7 +25,7 @@ Check out the [Fusion quickstart guide](/guides/fusion?step=1) to try the dbt VS
## Navigating the dbt extension
-Once the dbt VS Code extension has been installed, several visual enhancements will be added to your IDE to help you navigate the features and functionality.
+Once the dbt VS Code extension has been installed, several visual enhancements will be added to your IDE to help you navigate the features and functionality. To read more about the features and functionality, see the [dbt extension features](/docs/dbt-extension-features).
Check out the following video to see the features and functionality of the dbt VS Code extension:
diff --git a/website/docs/docs/dbt-extension-features.md b/website/docs/docs/dbt-extension-features.md
index 60bf9261a78..dd61424949e 100644
--- a/website/docs/docs/dbt-extension-features.md
+++ b/website/docs/docs/dbt-extension-features.md
@@ -24,8 +24,9 @@ The following extension features help you get more done, fast:
- If you use Cursor, the lineage tab works best in Editor mode and doesn't render in Agent mode. If you're in Agent mode and the lineage tab isn't rendering, just switch to Editor mode to view your project's table and column lineage.
- **[View compiled code](#view-compiled-code):** Get a live view of the SQL code your models will build alongside your dbt code.
- **[Build flexibly](#build-flexibly):** Use the command palette to build models with complex selectors.
+- **[Compare changes](#compare-changes):** Compare changes you make during development by comparing your current working copy against your `manifest.json` (for example, your last production state) — directly in your editor.
-### Live error detection
+## Live error detection
Automatically validate your SQL code to detect errors and surface warnings without hitting the warehouse.
@@ -41,7 +42,7 @@ Automatically validate your SQL code to detect errors and surface warnings witho
-### Lightning-fast parse times
+## Lightning-fast parse times
Parse even the largest projects up to 30x faster than with dbt Core.
@@ -49,7 +50,7 @@ Parse even the largest projects up to 30x faster than with dbt Core.
-### Powerful IntelliSense
+## Powerful IntelliSense
Autocomplete SQL functions, model names, macros and more.
@@ -59,7 +60,7 @@ Usage:
-### Instant refactoring
+## Instant refactoring
Renaming models:
- Right-click on a file in the file tree and select **Rename**.
@@ -79,7 +80,7 @@ Note: Renaming models and columns is not yet supported for snapshots, or any res
-### Go-to-definition and reference
+## Go-to-definition and reference
Jump to the definition of any `ref`, macro, model, or column with a single click. Particularly useful in large projects with many models and macros. Excludes definitions from installed packages.
@@ -92,7 +93,7 @@ Usage:
-### Hover insights
+## Hover insights
See context on tables, columns, and functions without leaving your code. Simply hover over any SQL element to see details like column names and data types.
@@ -104,7 +105,7 @@ Usage:
-### Live preview for models and CTEs
+## Live preview for models and CTEs
Preview a CTE’s output, or an entire model, directly from inside your editor for faster validation and debugging.
@@ -119,7 +120,7 @@ Usage:
-### Rich lineage in context
+## Rich lineage in context
See lineage at the column or table level as you develop — no context switching or breaking flow.
@@ -146,7 +147,7 @@ View column lineage:
-### View compiled code
+## View compiled code
Get a live view of the SQL code your models will build — right alongside your dbt code.
@@ -160,7 +161,7 @@ Usage:
-### Build flexibly
+## Build flexibly
Use the command palette to quickly build models using complex selectors.
@@ -171,3 +172,7 @@ Usage:
+
+import CompareChangesTLDR from '/snippets/_compare-changes-tldr.md';
+
+
diff --git a/website/docs/docs/deploy/advanced-ci.md b/website/docs/docs/deploy/advanced-ci.md
index 6310822e1b5..2401c3d3d3a 100644
--- a/website/docs/docs/deploy/advanced-ci.md
+++ b/website/docs/docs/deploy/advanced-ci.md
@@ -6,9 +6,12 @@ description: "Advanced CI enables developers to compare changes by demonstrating
image: /img/docs/dbt-cloud/example-ci-compare-changes-tab.png
---
+import CompareChangesTable from '/snippets/_compare-changes-table.md';
+
# Advanced CI
-[Continuous integration workflows](/docs/deploy/continuous-integration) help increase the governance and improve the quality of the data. Additionally for these CI jobs, you can use Advanced CI features, such as [compare changes](#compare-changes), that provide details about the changes between what's currently in your production environment and the pull request's latest commit, giving you observability into how data changes are affected by your code changes. By analyzing the data changes that code changes produce, you can ensure you're always shipping trustworthy data products as you're developing.
+[Continuous integration workflows](/docs/deploy/continuous-integration) help increase the governance and improve the quality of the data. Additionally for these CI jobs, you can use Advanced CI features, such as [compare changes](#compare-changes), that provide details about the changes between what's currently in your production environment and the pull request's latest commit, giving you observability into how data changes are affected by your code changes.
+By analyzing the data changes that code changes produce, you can ensure you're always shipping trustworthy data products as you're developing.
:::info How to enable this feature
@@ -23,14 +26,42 @@ You can opt into Advanced CI in . Please refer to [Acco
## Compare changes feature {#compare-changes}
+:::tip Compare changes in development
+
+You can use compare changes in development, powered by the , to preview changes to your data caused by your local edits (like added/removed rows and so on) — directly in your editor and without waiting on CI.
+
+For more details on how to use this feature, see [Compare changes in local development](/docs/fusion/vs-compare-changes).
+
+
+
+
+
+
+
+
+
+
+:::
+
+
For [CI jobs](/docs/deploy/ci-jobs) that have the [**dbt compare** option enabled](/docs/deploy/ci-jobs#set-up-ci-jobs), compares the changes between the last applied state of the production environment (defaulting to deferral for lower compute costs) and the latest changes from the pull request, whenever a pull request is opened or new commits are pushed.
+You can also compare changes in development. For more details, see [Compare changes in local development](/docs/fusion/vs-compare-changes).
+
dbt reports the comparison differences in:
- **** — Shows the changes (if any) to the data's primary keys, rows, and columns in the [Compare tab](/docs/deploy/run-visibility#compare-tab) from the [Job run details](/docs/deploy/run-visibility#job-run-details) page.
- **The pull request from your provider** — Shows a summary of the changes as a comment.
-
+
### Optimizing comparisons
@@ -65,6 +96,8 @@ If using dynamic data masking in the data warehouse, the cached data will no lon
+
+
## Troubleshooting
diff --git a/website/docs/docs/fusion/vs-compare-changes.md b/website/docs/docs/fusion/vs-compare-changes.md
new file mode 100644
index 00000000000..217bbb55923
--- /dev/null
+++ b/website/docs/docs/fusion/vs-compare-changes.md
@@ -0,0 +1,94 @@
+---
+title: "Compare changes in local development"
+id: "vs-compare-changes"
+description: "Compare how code edits will change your data while you develop in locally with the dbt VS Code extension — without waiting on CI."
+sidebar_label: "Compare changes"
+---
+
+# Compare changes in local development
+
+:::info
+Compare changes in local development, powered by , is available in beta for the VS Code extension.
+:::
+
+The dbt VS Code extension, powered by the , can preview and compare changes to your data caused by your local edits (like added/removed rows and so on) — directly in your editor and without waiting on CI.
+
+
+
+
+Compare changes in development is [different to Advanced CI compare changes](#how-this-differs-from-advanced-ci) in that it allows you to:
+- Check impact early on amd catch changes before you open a PR or run a [CI job](/docs/deploy/ci-jobs) in deployment.
+- Compare your current working copy against your `manifest.json` (for example, your last production state) — directly in your editor.
+- See the changes to the data's primary keys, rows, and columns in the **Compare** tab.
+
+Compare changes in development is available for models only, support for seeds, snapshots, ephemeral models, and Python models is coming soon.
+
+## Prerequisites
+
+- You have a dbt Enterprise or Enterprise+ account.
+- You have a developer seat license.
+- Installed the [dbt VS Code extension](/docs/install-dbt-extension) and the [](/docs/fusion/get-started-fusion) in your editor.
+- Enabled [Advanced CI features](/docs/cloud/account-settings#enabling-advanced-ci-features) in your account.
+- Use a supported data platform: BigQuery, Databricks, Redshift, or Snowflake. Support for additional data platforms coming soon.
+- If you've configured [automatic deferral](/docs/cloud/about-cloud-develop-defer), you need a successful job run. To use compare changes manually without a successful job run, you can manually copy a `manifest.json` and specify the state directory.
+
+#### How this differs from Advanced CI
+
+This compare changes feature applies to development only. If you're looking to compare changes between your production environment and the pull request’s latest commit, check out [Advanced CI compare changes](/docs/deploy/advanced-ci#compare-changes).
+
+import CompareChangesTable from '/snippets/_compare-changes-table.md';
+
+
+
+## Use compare changes
+
+To use compare changes in development, follow these steps:
+
+1. Open a SQL model file in your editor.
+2. Make sure to successfully build the model at least once with `dbt build`. This gives dbt a baseline for comparison and allows you to compare your changes against the last successful build of the model. If you don't have a successful build, compare changes won't work effectively.
+3. Make some changes to the model, like adding a new column or modifying an existing one (for example, `left_join_customers` to `right_join_customers`).
+4. Use the command palette and search for the [**dbt: Compare changes**](vscode://dbtLabsInc/dbt.compareModel) _or_ click the **Compare** tab in the editor toolbar.
+5. This runs the comparison and the [**Compare** tab](#compare-tab) displays the changes to the data's primary keys, rows, and columns. Clicking the tabs will display more details about the changes, like specific columns that were added or modified.
+6. Once you've compared changes and see the changes in the **Compare** tab, you can then decide to commit your changes or continue editing.
+
+
+
+
+## Compare tab
+The **Compare** tab displays the changes to the data's primary keys, rows, and columns. Clicking the tabs will display more details about the changes, like specific columns that were added or modified.
+
+
+
+- **Overview tab**: High-level summary about the changes to the models, such as the number of primary keys that were added or removed, rows modified, and so on. It will also include the relation between models that were added or modified.
+- **Primary keys tab**: Details about the changes to the records.
+- **Modified rows tab**: Details about the modified rows.
+- **Columns tab**: Details about the changes to the columns.
+
+## How it works
+
+Compare changes in development works by comparing your current working copy against your `manifest.json` (for example, your last production state) — directly in your editor. It uses the same credentials as the CI job, as defined in the CI job’s environment.
+
+ - If you're using 's deferral (recommended): Yes. You need at least one successful job run in the environment you are deferring to (usually production). This allows Fusion to auto-download the deferred manifest and use that as your baseline state.
+ - If you're manually setting a state directory: No. You can manually point the extension to a manifest.json (for example, copied from another environment) without needing a job run.run.
+
+## FAQs
+
+
+
+ Yes. All comparison queries in development are run using your local development credentials, directly from the dbt VS Code extension. The uses your credentials to execute comparison queries in your warehouse. The results are stored locally by the extension for caching and faster repeated comparisons.
+
+
+ Yes. Because the comparison runs in your development environment using your dev credentials, it will use your warehouse’s compute.
+
+
+ You don’t need to run `dbt build` after every change, but you do need at least one successful build per model to establish the baseline.
+ - You need one successful `build` of the model to create a baseline table for comparison.
+ - After that, you can edit your model and run **Compare** without rebuilding every time.
+ - If your model becomes invalid (for example, errors or breaking schema changes), you’ll need to rebuild to create a new valid baseline before comparing again.
+
+
+ Not yet, but Python models are expected to work once Fusion support is available because compare changes only relies on the resulting table in the warehouse.
+
+
+## Related docs
+- [Advanced CI compare changes](/docs/deploy/advanced-ci#compare-changes)
diff --git a/website/sidebars.js b/website/sidebars.js
index 7b8a38496e5..a4059f63fc6 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -373,6 +373,7 @@ const sidebarSettings = {
"docs/about-dbt-extension",
"docs/dbt-extension-features",
"docs/install-dbt-extension",
+ "docs/fusion/vs-compare-changes",
"docs/configure-dbt-extension",
],
},
diff --git a/website/snippets/_compare-changes-tldr.md b/website/snippets/_compare-changes-tldr.md
new file mode 100644
index 00000000000..8d5bbf77045
--- /dev/null
+++ b/website/snippets/_compare-changes-tldr.md
@@ -0,0 +1,7 @@
+## Compare changes in development
+
+You can use compare changes in development, powered by the , to compare your current working copy against your `manifest.json` (for example, your last production state) — directly in your editor.
+
+For more details on how to use this feature, see [Compare changes in local development](/docs/fusion/vs-compare-changes).
+
+
diff --git a/website/static/img/docs/extension/compare-changes-dev-tab.jpg b/website/static/img/docs/extension/compare-changes-dev-tab.jpg
new file mode 100644
index 00000000000..00695625a4c
Binary files /dev/null and b/website/static/img/docs/extension/compare-changes-dev-tab.jpg differ
diff --git a/website/static/img/docs/extension/vs-compare-changes.gif b/website/static/img/docs/extension/vs-compare-changes.gif
new file mode 100644
index 00000000000..56fedb401a9
Binary files /dev/null and b/website/static/img/docs/extension/vs-compare-changes.gif differ