Add Sankey chart documentation

docs.json

@@ -73,6 +73,7 @@
                       "references/chart-types/pie-chart",
                       "references/chart-types/funnel-chart",
                       "references/chart-types/treemap-chart",
+                      "references/chart-types/sankey",
                       "references/chart-types/table",
                       "references/chart-types/big-value",
                       "references/chart-types/gauge",

references/chart-types/overview.mdx

@@ -14,6 +14,7 @@ In Lightdash, the data in your results tables can be visualized in a bunch of di
 - [Pie chart](/references/chart-types/pie-chart)
 - [Funnel chart](/references/chart-types/funnel-chart)
 - [Treemap chart](/references/chart-types/treemap-chart)
+- [Sankey chart](/references/chart-types/sankey)
 - [Table](/references/chart-types/table)
 - [Big value](/references/chart-types/big-value)
 - [Gauge](/references/chart-types/gauge)

references/chart-types/sankey.mdx

@@ -0,0 +1,69 @@
+---
+title: "Sankey chart"
+description: "Use Sankey charts to visualize flows between categories, showing how values move from sources to targets."
+icon: "diagram-sankey"
+---
+
+<Note>
+  This feature is in [Early Access](/references/workspace/feature-maturity-levels). We'd love your feedback as we continue to improve it.
+</Note>
+
+<Frame>
+![](/images/references/chart-types/sankey.png)
+</Frame>
+
+Sankey diagrams visualize flows between categories — how values move from a source to a target, weighted by a metric. They're ideal for understanding movement, distribution, or conversion across stages.
+
+Sankey charts are useful when:
+
+- You want to show how values flow between categories (e.g., marketing channels → conversions)
+- You're visualizing multi-step processes or funnels
+- You need to understand distribution across interconnected stages
+- You have cyclical flows that loop back (e.g., retargeting → conversion → retargeting)
+
+## Data requirements
+
+Sankey charts require **three columns** in your data:
+
+| Column type | Description | Example |
+|-------------|-------------|---------|
+| **Source dimension** | Where the flow originates | `channel`, `referrer`, `stage_from` |
+| **Target dimension** | Where the flow goes | `conversion_type`, `destination`, `stage_to` |
+| **Weight metric** | The size of the flow | `count`, `revenue`, `users` |
+
+Each row in your data represents a flow from one node to another, with the weight determining the thickness of the connection.
+
+## Creating a Sankey chart
+
+1. Run a query with your source dimension, target dimension, and weight metric
+2. Select **Sankey** from the chart type picker
+3. In the configuration panel, assign:
+   - **Source** — the dimension representing flow origins
+   - **Target** — the dimension representing flow destinations  
+   - **Value** — the metric determining flow size
+
+## Features
+
+### Multi-step flows
+
+Sankey charts automatically handle nodes that appear as both sources and targets, creating multi-level visualizations. For example, if "Email" appears as a target from "Ad Click" and as a source to "Purchase", the chart will show the full flow path.
+
+### Cyclical flows
+
+Unlike traditional Sankey implementations, Lightdash supports cyclical data where flows can loop back. For example, in a retargeting funnel:
+
+- Awareness → Consideration
+- Consideration → Conversion
+- Conversion → Retargeting
+- Retargeting → Conversion (loop)
+
+The chart handles these cycles by creating step-suffixed node instances (e.g., "Conversion - Step 2").
+
+## Layout options
+
+- **Orientation** — Display flows horizontally (left to right) or vertically (top to bottom)
+- **Node alignment** — Align nodes to the left, right, or justify across the chart
+
+## Display options
+
+- **Color customization** — Configure colors per depth level or override for specific nodes