diff --git a/docs/assets/images/features/cll-1.png b/docs/assets/images/features/cll-1.png index 7b2588e..3623670 100644 Binary files a/docs/assets/images/features/cll-1.png and b/docs/assets/images/features/cll-1.png differ diff --git a/docs/assets/images/features/cll-2.png b/docs/assets/images/features/cll-2.png index 11e67b3..72266b7 100644 Binary files a/docs/assets/images/features/cll-2.png and b/docs/assets/images/features/cll-2.png differ diff --git a/docs/assets/images/features/cll-3.png b/docs/assets/images/features/cll-3.png index e89bdfe..a5fe7ca 100644 Binary files a/docs/assets/images/features/cll-3.png and b/docs/assets/images/features/cll-3.png differ diff --git a/docs/assets/images/features/impact-radius-1.png b/docs/assets/images/features/impact-radius-1.png new file mode 100644 index 0000000..026b383 Binary files /dev/null and b/docs/assets/images/features/impact-radius-1.png differ diff --git a/docs/assets/images/features/impact-radius-2.png b/docs/assets/images/features/impact-radius-2.png new file mode 100644 index 0000000..1559339 Binary files /dev/null and b/docs/assets/images/features/impact-radius-2.png differ diff --git a/docs/assets/images/features/impact-radius-3.png b/docs/assets/images/features/impact-radius-3.png new file mode 100644 index 0000000..e9b6bc4 Binary files /dev/null and b/docs/assets/images/features/impact-radius-3.png differ diff --git a/docs/assets/images/features/impact-radius-legacy.png b/docs/assets/images/features/impact-radius-legacy.png new file mode 100644 index 0000000..91e8b23 Binary files /dev/null and b/docs/assets/images/features/impact-radius-legacy.png differ diff --git a/docs/assets/images/features/impact-radius-single-1.png b/docs/assets/images/features/impact-radius-single-1.png new file mode 100644 index 0000000..f02d6d3 Binary files /dev/null and b/docs/assets/images/features/impact-radius-single-1.png differ diff --git a/docs/assets/images/features/impact-radius-single-2.png b/docs/assets/images/features/impact-radius-single-2.png new file mode 100644 index 0000000..a74b693 Binary files /dev/null and b/docs/assets/images/features/impact-radius-single-2.png differ diff --git a/docs/assets/images/features/impact-radius-single-3.png b/docs/assets/images/features/impact-radius-single-3.png new file mode 100644 index 0000000..4d6a676 Binary files /dev/null and b/docs/assets/images/features/impact-radius-single-3.png differ diff --git a/docs/assets/images/features/impact-radius.png b/docs/assets/images/features/impact-radius.png new file mode 100644 index 0000000..e990fa2 Binary files /dev/null and b/docs/assets/images/features/impact-radius.png differ diff --git a/docs/features/breaking-change-analysis.md b/docs/features/breaking-change-analysis.md index c33390b..f2c5fed 100644 --- a/docs/features/breaking-change-analysis.md +++ b/docs/features/breaking-change-analysis.md @@ -12,37 +12,103 @@ icon: octicons/diff-modified-24 It's generally assumed that any modification to a model’s SQL will affect all downstream models. However, not all changes have the same level of impact. For example, formatting adjustments or the addition of a new column should not break downstream dependencies. Breaking change analysis helps you assess whether a change affects downstream models and, if so, to what extent. +## Usage +Use the [impact radius](./impact-radius.md#usage) view to analyze changed and see the impacted downstream. + ## Categories of change -Category | Downstream Impact | Examples ----|---|--- -Non-breaking change | No downstream models are affected | New column, formatting SQL, adding comments -Partial breaking change | Only downstream models referencing certain columns are affected | Removing, renaming, or modifying the definition of a column -Breaking change | All downstream models are affected | Changing filter conditions (e.g. `WHERE`), sort order (`ORDER BY`), or other SQL logic +### Non-breaking change + +No downstream models are affected. Common cases are adding new columns, comments, or formatting changes that don't alter logic. + +**Example: Add new columns** +Adding a new column like status doesn't affect models that don't reference it. + +```diff +select + user_id, + user_name, +++ status, +from + {{ ref("orders") }} + +``` + + + + +### Partial breaking change + +Only downstream models that reference specific columns are affected. Common cases are removing, renaming, or redefining a column. + +**Example: Removing a column** + +```diff +select + user_id, +-- status, + order_date, +from + {{ ref("orders") }} +``` + +**Example: Renaming a column** + +```diff +select + user_id, +-- status +++ order_status +from + {{ ref("orders") }} +``` + + +**Example: Redefining a column** +```diff +select + user_id, +-- discount +++ coalesce(discount, 0) as discount +from + {{ ref("orders") }} +``` -## Usage -To enable **Breaking Change Analysis**, click the toggle on the **Lineage** page. +### Breaking change -All modified models display their change category directly on the node. Additionally, partial breaking changes are highlighted with a dashed orange border to indicate that they may not impact downstream models. +All downstream models are affected. Common case are changes adding a filter condition or adding group by columns. -=== "Disabled" - - ![Breaking Change Analysis (disabled)](../assets/images/features/breaking-change-disabled.png){: .shadow} +**Example: Adding a filter condition** +This may reduce the number of rows, affecting all downstream logic that depends on the original row set. -=== "Enabled" - - ![Breaking Change Analysis](../assets/images/features/breaking-change.png){: .shadow} +```diff +select + user_id, + order_date +from + {{ ref("orders") }} +++ where status = 'completed' +``` -## Column-Level Lineage +**Example: Adding a GROUP BY column** +Changes the granularity of the result set, which can break all dependent models. -In models classified as **non-breaking** or **partial breaking** - added, removed, or modified columns will be listed. Click on a column to open its [Column-Level Lineage](./column-level-lineage.md) +```diff +select + user_id, +++ order_data, + count(*) as total_orders +from + {{ ref("orders") }} +-- group by user_id +++ group by user_id, order_date +``` -![Column-level lineage](../assets/images/features/breaking-change-lineage.png){: .shadow} ## Limitations -The current implementation of breaking change analysis is still very conservative. As a result, a modified model may be classified as a breaking change when it is actually non breaking or partial breaking changes. Common cases include: +Our breaking change analysis is intentionally conservative to prioritize safety. As a result, a modified model may be classified as a breaking change when it is actually non breaking or partial breaking changes. Common cases include: 1. Logical equivalence in operations, such as changing `a + b` to `b + a`. 1. Adding a `LEFT JOIN` to a table and selecting columns from it. This is often used to enrich the current model with additional dimension table data without affecting existing downstream tables. diff --git a/docs/features/impact-radius.md b/docs/features/impact-radius.md new file mode 100644 index 0000000..b3f2068 --- /dev/null +++ b/docs/features/impact-radius.md @@ -0,0 +1,82 @@ +--- +title: Impact Radius +icon: material/adjust +--- + +**Impact Radius** helps you analyze changes and identify downstream impacts at the column level. + +While dbt provides a similar capability using the [state selector](https://docs.getdbt.com/reference/node-selection/methods#state) with `state:modified+` to identify modified nodes and their downstream dependencies, Recce goes further. By analyzing SQL code directly, Recce enables **fine-grained impact radius analysis**. It reveals how changes to specific columns can ripple through your data pipeline, helping you prioritize which models—and even which columns—deserve closer attention. + + +=== "state:modified+" + + ![Breaking Change Analysis (disabled)](../assets/images/features/impact-radius-legacy.png){: .shadow} + +=== "Impact Radius" + + ![Breaking Change Analysis](../assets/images/features/impact-radius.png){: .shadow} + + + +## Usage + +### Show impact radius + +1. Click the **Impact Radius** button in the upper-left corner. + + ![Impact Radius button highlighted](../assets/images/features/impact-radius-1.png){: .shadow} + +1. The impact radius will be displayed. + + ![Impact radius displayed on screen](../assets/images/features/impact-radius-2.png){: .shadow} + +1. To exit impact radius view, click the close button in the upper-left corner. + + ![Close button for exiting impact radius view](../assets/images/features/impact-radius-3.png){: .shadow} + +### Show impact radius for a single changed model + +1. Hover over a changed model, then click the **target icon** or right-click the model and click the **Show Impact Radius** + + ![Target icon for showing impact radius of a single model](../assets/images/features/impact-radius-single-1.png){: .shadow} + +1. The impact radius for this model will be displayed. + + ![Impact radius for a single model displayed on screen](../assets/images/features/impact-radius-single-2.png){: .shadow} + +1. To exit impact radius view, click the close button in the upper-left corner. + + ![Close button for exiting single model impact radius view](../assets/images/features/impact-radius-single-3.png){: .shadow} + + +## How it works + +Two core features power the impact radius analysis: + +**[Breaking Change Analysis](./breaking-change-analysis.md)** classifies modified models into three categories: + +- **Breaking changes**: Impact all downstream **models** +- **Non-breaking changes**: Do not impact any downstream **models** +- **Partial breaking changes**: Impact only downstream **models or columns** that depend on the modified columns + +**[Column-level lineage](./column-level-lineage.md)** analyzes your model's SQL to identify column-level dependencies: + +- Which upstream **columns** are used as filters or grouping keys. If those upstream **columns** change, the current **model** is impacted. +- Which upstream **columns** a specific column references. If those upstream **columns** change, the specific **column** is impacted. + +## Putting It Together + +With the insights from the two features above, Recce determines the impact radius: + +1. If a model has a **breaking change**, include all downstream models in the impact radius. +1. If a model has a **non-breaking change**, include only the downstream columns and models of newly added columns. +1. If a model has a **partial breaking change**, include the downstream columns and models of added, removed, or modified columns. + + + + + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index 6992912..e0e259d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,6 +56,7 @@ nav: - features/state-file.md - features/preset-checks.md - features/node-selection.md + - features/impact-radius.md - features/breaking-change-analysis.md - features/column-level-lineage.md - reference/configuration.md