Skip to content

Add impact radius doc #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 8, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified docs/assets/images/features/cll-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/images/features/cll-2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/assets/images/features/cll-3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/images/features/impact-radius-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/images/features/impact-radius-2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/images/features/impact-radius-3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/images/features/impact-radius.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
102 changes: 84 additions & 18 deletions docs/features/breaking-change-analysis.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
82 changes: 82 additions & 0 deletions docs/features/impact-radius.md
Original file line number Diff line number Diff line change
@@ -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.









1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down