You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on May 9, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: docs/docs/features/breaking-change-analysis.md
+20-10Lines changed: 20 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,21 +3,27 @@ title: Breaking Change Analysis
3
3
icon: octicons/diff-modified-24
4
4
---
5
5
6
-
Breaking change analysis examines models for modifications to the SQL semantic tree that could potentially alter the data generated by the model, resulting in downstream impact.
6
+
**Breaking Change Analysis** examines modified models and categorizes changes into three types:
7
7
8
-
Currently, all modified models are treated as **breaking changes** unless:
8
+
- Breaking changes
9
+
- Partial breaking changes
10
+
- Non-breaking changes
9
11
10
-
1. The semantics are unchanged.
11
-
1. The modification only involves adding a new column.
12
+
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.
12
13
13
-
If no structural differences are detected or the changes involve simply adding new columns, the modification is classified as non-breaking changes.
14
+
15
+
## Categories of change
16
+
Category | Downstream Impact | Examples
17
+
---|---|---
18
+
Non-breaking change | No downstream models are affected | New column, formatting SQL, adding comments
19
+
Partial breaking change | Only downstream models referencing certain columns are affected | Removing, renaming, or modifying the definition of a column
20
+
Breaking change | All downstream models are affected | Changing filter conditions (e.g. `WHERE`), sort order (`ORDER BY`), or other SQL logic
14
21
15
22
## Usage
16
23
17
-
To enable the feature, click the **breaking Change Analysis** toggle on the **Lineage** page.
24
+
To enable **Breaking Change Analysis**, click the toggle on the **Lineage** page.
18
25
19
-
- Models with **breaking changes** can be identified by a solid orange border.
20
-
- Models with **non-breaking changes** can be identified by the dashed orange border.
26
+
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.
21
27
22
28
=== "Disabled"
23
29
@@ -28,12 +34,16 @@ To enable the feature, click the **breaking Change Analysis** toggle on the **L
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)
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. Common cases include:
45
+
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 nonbreaking or partial breaking changes. Common cases include:
35
46
36
-
1. Adding a column using a `CASE WHEN` statement.
37
47
1. Logical equivalence in operations, such as changing `a + b` to `b + a`.
38
48
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.
39
49
1. All modified python models or seeds are treated as breaking change.
## Share your validation results with anyone, no setup needed
7
+
8
+
If you've already used Recce to validate your PR and prepared checks, but stakeholders might not have the environment to run Recce.
9
+
10
+
Recce Cloud allows you to share your Recce validation results with full context, using a simple link. Stakeholders can open a read-only Recce view directly in their browser. No installation, no configuration, just instant access.
11
+
12
+
!!! Note
13
+
14
+
Please note that anyone with the link can visit your shared Recce after sign in Recce Cloud. If you need to restrict access, [please contact us](https://cal.com/team/recce/chat).
15
+
16
+
## How to use
17
+
18
+
When you're ready to share your lineage exploration, query results, or validation checklist, simply click **Share** in Recce.
19
+
20
+
The first time you do this, you'll need to connect your local Recce to Recce Cloud. This requires signing in and setting up an API token. Once connected, Recce Cloud will host your state file securely, allowing you to share a link that others can open in their browsers.
21
+
22
+
1. Enable Recce Sharing
23
+
24
+
To start sharing, launch Recce server and click the **Enable Sharing** button.
Copy your API token from the [personal settings page](https://cloud.datarecce.io/settings#tokens) in Recce Cloud.
31
+
32
+
{: .shadow}
33
+
34
+
1. Add the token to `.recce/profile.yml`
35
+
36
+
For convenience, you can add your API token in `.recce/profile.yml`, located by default in your home directory.
37
+
```yaml
38
+
user_id: <your_user_id>
39
+
api_token: <your_api_token>
40
+
```
41
+
Alternatively, for one-time use, you can use `--api-token` flag with commend. e.g.,
42
+
```bash
43
+
recce server --api-token <your_api_token>
44
+
```
45
+
46
+
1. Relaunch Recce server
47
+
48
+
After adding the API token, restarting Recce server is required to load the new configuration.
49
+
Once it's running, you'll see the **Share** button, then you can click it to get the link on top.
50
+
51
+
{: .shadow}
52
+
53
+
You can also use the `recce share` command. If you already have a prepared Recce state file, you can obtain a share link directly through the command line.
54
+
```bash
55
+
recce share <your_state_file>
56
+
recce share --api-token <your_api_token> <your_state_file> # for one-time use
57
+
```
58
+
{: .shadow}
0 commit comments