sql-glider 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

{sql_glider-0.1.23.dist-info → sql_glider-0.1.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-glider
-Version: 0.1.23
+Version: 0.1.25
 Summary: SQL Utility Toolkit for better understanding, use, and governance of your queries in a native environment.
 Project-URL: Homepage, https://github.com/rycowhi/sql-glider/
 Project-URL: Repository, https://github.com/rycowhi/sql-glider/
@@ -28,6 +28,8 @@ Requires-Dist: sqlglot[rs]>=25.0.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: databricks
 Requires-Dist: databricks-sdk>=0.20.0; extra == 'databricks'
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.0.0; extra == 'plotly'
 Description-Content-Type: text/markdown
 
 # SQL Glider
@@ -420,12 +422,33 @@ uv run sqlglider graph query graph.json --upstream orders.customer_id -f mermaid
 # Query with DOT (Graphviz) diagram output
 uv run sqlglider graph query graph.json --downstream customers.id -f dot
 
+# Query with Plotly JSON output (for interactive visualization)
+uv run sqlglider graph query graph.json --upstream orders.customer_id -f plotly
+
 # Visualize entire graph as a diagram
 uv run sqlglider graph visualize graph.json                    # Mermaid (default)
 uv run sqlglider graph visualize graph.json -f dot             # DOT/Graphviz
+uv run sqlglider graph visualize graph.json -f plotly          # Plotly JSON
 uv run sqlglider graph visualize graph.json -o lineage.mmd     # Save to file
 ```
 
+> **Note:** Plotly output requires an optional dependency. Install with: `pip install sql-glider[plotly]`
+
+The Plotly JSON output can be loaded into Plotly/Dash applications for interactive visualization:
+
+```python
+import plotly.io as pio
+from dash import Dash, dcc, html
+
+# Load the JSON output
+with open("lineage.json") as f:
+    fig = pio.from_json(f.read())
+
+# Use in a Dash app
+app = Dash(__name__)
+app.layout = html.Div([dcc.Graph(figure=fig)])
+```
+
 **Example Upstream Query Output:**
 ```
                               Sources for 'order_totals.total'
@@ -711,12 +734,24 @@ Arguments:
 Options:
   --upstream, -u              Find source columns for this column [optional]
   --downstream, -d            Find affected columns for this source [optional]
-  --output-format, -f         Output format: 'text', 'json', or 'csv' [default: text]
+  --output-format, -f         Output format: 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', 'dot', or 'plotly' [default: text]
+```
+
+```
+sqlglider graph visualize <graph_file> [OPTIONS]
+
+Arguments:
+  graph_file                  Path to graph JSON file [required]
+
+Options:
+  --output-format, -f         Diagram format: 'mermaid', 'mermaid-markdown', 'dot', or 'plotly' [default: mermaid]
+  --output-file, -o           Write diagram to file instead of stdout [optional]
 ```
 
 **Notes:**
 - `--upstream` and `--downstream` are mutually exclusive. Use one or the other.
 - Graph queries are case-insensitive for column matching.
+- Plotly output requires optional dependency: `pip install sql-glider[plotly]`
 
 ## Output Formats
 
@@ -921,6 +956,21 @@ UV_PUBLISH_TOKEN=pypi-...
 - **pydantic:** Data validation and serialization
 - **rustworkx:** High-performance graph library for cross-file lineage analysis
 
+### Optional Dependencies
+
+Install optional features with extras:
+
+```bash
+# Databricks catalog integration
+pip install sql-glider[databricks]
+
+# Plotly interactive visualization
+pip install sql-glider[plotly]
+
+# Install multiple extras
+pip install sql-glider[databricks,plotly]
+```
+
 ## References
 
 - [SQLGlot Documentation](https://sqlglot.com/)

{sql_glider-0.1.23.dist-info → sql_glider-0.1.25.dist-info}/RECORD

@@ -1,6 +1,6 @@
 sqlglider/__init__.py,sha256=gDf7s52dMcX7JuCZ1SLawcB1vb3U0yJCohu9RQAATBY,125
-sqlglider/_version.py,sha256=eZj6tqY-zTtH5r_8y6a4Vovz6LQ_hDHSesTIiwuyahQ,706
-sqlglider/cli.py,sha256=yvCkwU75aCSwExXcu0xHpMMI2G5X6L-DViP44nUgs5A,68548
+sqlglider/_version.py,sha256=VIORluFSyo8DggJNI3m2ltXngK-bmCHX8hSwlGrwopY,706
+sqlglider/cli.py,sha256=h0dAx-Dz_LkSfrWlxD8wU_G2WzWqzn14EjHAwajWVyQ,69591
 sqlglider/global_models.py,sha256=2vyJXAuXOsXQpE-D3F0ejj7eR9z0nDWFjTkielhzM8k,356
 sqlglider/catalog/__init__.py,sha256=2PqFPyzFXJ14FpSUcBmVK2L-a_ypWQHAbHFHxLDk_LE,814
 sqlglider/catalog/base.py,sha256=R7htHC43InpH4uRjYk33dMYYji6oylHns7Ye_mgfjJE,3116
@@ -12,7 +12,7 @@ sqlglider/dissection/formatters.py,sha256=M7gsmTNljRIeLIRv4D0vHvqJVrTqWSpsg7vem8
 sqlglider/dissection/models.py,sha256=RRD3RIteqbUBY6e-74skKDvMH3qeAUaqA2sFcrjP5GQ,3618
 sqlglider/graph/__init__.py,sha256=4DDdrPM75CmeQWt7wHdBsjCm1s70BHGLYdijIbaUEKY,871
 sqlglider/graph/builder.py,sha256=VNBdsDlkiaId3JGvr2G4h6OIFek_9zPsGMIYL9GpJlk,15796
-sqlglider/graph/diagram_formatters.py,sha256=loCpT343Awuj1mue8pv2fNTfwrLfK8n9adlfpPI_OQw,10825
+sqlglider/graph/diagram_formatters.py,sha256=-7BFG3z4EZrmiwnOAco-R-Axs5OL57ytMXGHuTh0z68,25321
 sqlglider/graph/formatters.py,sha256=p85-WN9oPmEETsAtWSo1sIQELF36w85QoFEJyfBZGoM,4800
 sqlglider/graph/merge.py,sha256=uUZlm4BN3S9gRL66Cc2mzhbtuh4SVAv2n4cN4eUEQBU,4077
 sqlglider/graph/models.py,sha256=EYmjv_WzDSNp_WfhJ6H-qBIOkAcoNKS7GRUryfKrHuY,9330
@@ -32,8 +32,8 @@ sqlglider/utils/__init__.py,sha256=KGp9-UzKz_OFBOTFoSy-g-NXDZsvyWXG_9-1zcC6ePE,2
 sqlglider/utils/config.py,sha256=qx5zE9pjLCCzHQDFVPLVd7LgJ-lghxUa2x-aZOAHByY,4962
 sqlglider/utils/file_utils.py,sha256=5_ff28E0r1R7emZzsOnRuHd-7zIX6873eyr1SuPEr4E,1093
 sqlglider/utils/schema.py,sha256=LiWrYDunXKJdoSlpKmIaIQ2hLSaIN1iQHqkXjMpGzRE,1883
-sql_glider-0.1.23.dist-info/METADATA,sha256=kus6plflZU9p594ooQRsVkeYgEPyW8V_hbvCyMUGid8,29695
-sql_glider-0.1.23.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-sql_glider-0.1.23.dist-info/entry_points.txt,sha256=HDuakHqHS5C0HFKsMIxMYmDU7-BLBGrnIJcYaVRu-s0,251
-sql_glider-0.1.23.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-sql_glider-0.1.23.dist-info/RECORD,,
+sql_glider-0.1.25.dist-info/METADATA,sha256=qCGtZ5ROBNQbi-9NDmWUNdf9WtIG9NQoEVrplFzXsxs,31197
+sql_glider-0.1.25.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sql_glider-0.1.25.dist-info/entry_points.txt,sha256=HDuakHqHS5C0HFKsMIxMYmDU7-BLBGrnIJcYaVRu-s0,251
+sql_glider-0.1.25.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+sql_glider-0.1.25.dist-info/RECORD,,

sqlglider/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.23'
-__version_tuple__ = version_tuple = (0, 1, 23)
+__version__ = version = '0.1.25'
+__version_tuple__ = version_tuple = (0, 1, 25)
 
 __commit_id__ = commit_id = None

sqlglider/cli.py

@@ -1642,7 +1642,7 @@ def graph_query(
         "text",
         "--output-format",
         "-f",
-        help="Output format: 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', or 'dot'",
+        help="Output format: 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', 'dot', or 'plotly'",
     ),
 ) -> None:
     """
@@ -1661,6 +1661,9 @@ def graph_query(
 
         # CSV output
         sqlglider graph query graph.json --downstream orders.order_id -f csv
+
+        # Plotly JSON output (for Dash/Plotly visualization)
+        sqlglider graph query graph.json --upstream orders.total -f plotly
     """
     from sqlglider.graph.query import GraphQuerier
 
@@ -1685,10 +1688,11 @@ def graph_query(
         "mermaid",
         "mermaid-markdown",
         "dot",
+        "plotly",
     ]:
         err_console.print(
             f"[red]Error:[/red] Invalid output format '{output_format}'. "
-            "Use 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', or 'dot'."
+            "Use 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', 'dot', or 'plotly'."
         )
         raise typer.Exit(1)
 
@@ -1720,6 +1724,14 @@ def graph_query(
             from sqlglider.graph.diagram_formatters import DotFormatter
 
             print(DotFormatter.format_query_result(result))
+        elif output_format == "plotly":
+            from sqlglider.graph.diagram_formatters import PlotlyFormatter
+
+            print(PlotlyFormatter.format_query_result(result, graph=querier.graph))
+
+    except ImportError as e:
+        err_console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
 
     except FileNotFoundError as e:
         err_console.print(f"[red]Error:[/red] {e}")
@@ -1825,7 +1837,7 @@ def graph_visualize(
         "mermaid",
         "--output-format",
         "-f",
-        help="Diagram format: 'mermaid', 'mermaid-markdown', or 'dot'",
+        help="Diagram format: 'mermaid', 'mermaid-markdown', 'dot', or 'plotly'",
     ),
     output_file: Optional[Path] = typer.Option(
         None,
@@ -1837,8 +1849,8 @@ def graph_visualize(
     """
     Visualize the entire lineage graph as a diagram.
 
-    Generates Mermaid or DOT (Graphviz) diagrams showing all nodes and edges
-    in the graph for visualization tools.
+    Generates Mermaid, DOT (Graphviz), or Plotly JSON diagrams showing all
+    nodes and edges in the graph for visualization tools.
 
     Examples:
 
@@ -1853,18 +1865,16 @@ def graph_visualize(
 
         # Render DOT to PNG with Graphviz
         sqlglider graph visualize graph.json -f dot -o lineage.dot
+
+        # Generate Plotly JSON for Dash/Plotly apps
+        sqlglider graph visualize graph.json -f plotly -o lineage.json
     """
-    from sqlglider.graph.diagram_formatters import (
-        DotFormatter,
-        MermaidFormatter,
-        MermaidMarkdownFormatter,
-    )
     from sqlglider.graph.serialization import load_graph
 
-    if output_format not in ["mermaid", "mermaid-markdown", "dot"]:
+    if output_format not in ["mermaid", "mermaid-markdown", "dot", "plotly"]:
         err_console.print(
             f"[red]Error:[/red] Invalid output format '{output_format}'. "
-            "Use 'mermaid', 'mermaid-markdown', or 'dot'."
+            "Use 'mermaid', 'mermaid-markdown', 'dot', or 'plotly'."
         )
         raise typer.Exit(1)
 
@@ -1872,11 +1882,21 @@ def graph_visualize(
         graph = load_graph(graph_file)
 
         if output_format == "mermaid":
+            from sqlglider.graph.diagram_formatters import MermaidFormatter
+
             diagram = MermaidFormatter.format_full_graph(graph)
         elif output_format == "mermaid-markdown":
+            from sqlglider.graph.diagram_formatters import MermaidMarkdownFormatter
+
             diagram = MermaidMarkdownFormatter.format_full_graph(graph)
-        else:
+        elif output_format == "dot":
+            from sqlglider.graph.diagram_formatters import DotFormatter
+
             diagram = DotFormatter.format_full_graph(graph)
+        else:  # plotly
+            from sqlglider.graph.diagram_formatters import PlotlyFormatter
+
+            diagram = PlotlyFormatter.format_full_graph(graph)
 
         if output_file:
             output_file.write_text(diagram, encoding="utf-8")
@@ -1884,6 +1904,10 @@ def graph_visualize(
         else:
             print(diagram)
 
+    except ImportError as e:
+        err_console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
     except FileNotFoundError as e:
         err_console.print(f"[red]Error:[/red] {e}")
         raise typer.Exit(1)

sqlglider/graph/diagram_formatters.py

@@ -1,7 +1,9 @@
-"""Diagram formatters for lineage graphs (Mermaid and DOT/Graphviz)."""
+"""Diagram formatters for lineage graphs (Mermaid, DOT/Graphviz, and Plotly)."""
 
+import json
 import re
-from typing import Set
+from collections import defaultdict
+from typing import Any, Optional, Set
 
 from sqlglider.graph.models import LineageGraph
 from sqlglider.graph.query import LineageQueryResult
@@ -328,3 +330,409 @@ class DotFormatter:
 
         lines.append("}")
         return "\n".join(lines)
+
+
+def _compute_layered_layout(
+    nodes: list[str],
+    edges: list[tuple[str, str]],
+    x_spacing: float = 250.0,
+    y_spacing: float = 100.0,
+) -> dict[str, tuple[float, float]]:
+    """Compute layered layout positions for nodes using topological ordering.
+
+    Positions nodes in layers from left to right based on their dependencies.
+    Nodes with no incoming edges are placed in layer 0, their dependents in
+    layer 1, etc.
+
+    Args:
+        nodes: List of node identifiers
+        edges: List of (source, target) edge tuples
+        x_spacing: Horizontal spacing between layers (default: 250 pixels)
+        y_spacing: Vertical spacing between nodes in the same layer (default: 100 pixels)
+
+    Returns:
+        Dictionary mapping node identifiers to (x, y) positions
+    """
+    if not nodes:
+        return {}
+
+    # Build adjacency structures
+    incoming: dict[str, set[str]] = defaultdict(set)
+    outgoing: dict[str, set[str]] = defaultdict(set)
+    for src, tgt in edges:
+        outgoing[src].add(tgt)
+        incoming[tgt].add(src)
+
+    # Assign layers via modified Kahn's algorithm
+    layers: dict[str, int] = {}
+    node_set = set(nodes)
+
+    # Start with nodes that have no incoming edges (roots)
+    current_layer = [n for n in nodes if not incoming[n]]
+    if not current_layer:
+        # Cycle detected or all nodes have incoming edges, use first node
+        current_layer = [nodes[0]]
+
+    layer_num = 0
+    while current_layer:
+        next_layer = []
+        for node in current_layer:
+            if node not in layers:
+                layers[node] = layer_num
+            for child in outgoing[node]:
+                if child in node_set and child not in layers:
+                    # Check if all parents are assigned
+                    if all(p in layers for p in incoming[child]):
+                        next_layer.append(child)
+        layer_num += 1
+        current_layer = next_layer
+
+    # Assign any remaining unvisited nodes to the last layer
+    for node in nodes:
+        if node not in layers:
+            layers[node] = layer_num
+
+    # Group nodes by layer for vertical positioning
+    layer_groups: dict[int, list[str]] = defaultdict(list)
+    for node, layer in layers.items():
+        layer_groups[layer].append(node)
+
+    # Compute positions: x based on layer, y spread vertically within layer
+    positions: dict[str, tuple[float, float]] = {}
+
+    for layer, layer_nodes in layer_groups.items():
+        x = layer * x_spacing
+        n = len(layer_nodes)
+        for i, node in enumerate(sorted(layer_nodes)):
+            # Center nodes vertically, spread them out uniformly
+            y = (i - (n - 1) / 2) * y_spacing
+            positions[node] = (x, y)
+
+    return positions
+
+
+class PlotlyFormatter:
+    """Format lineage graphs as Plotly JSON figure specifications.
+
+    Generates JSON that can be loaded into Plotly/Dash applications using
+    plotly.io.from_json() or directly into dcc.Graph components.
+
+    Requires the 'plotly' optional dependency: pip install sql-glider[plotly]
+    """
+
+    @staticmethod
+    def _check_plotly_available() -> None:
+        """Check if plotly is installed, raise ImportError if not."""
+        try:
+            import plotly  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "Plotly is required for this output format. "
+                "Install it with: pip install sql-glider[plotly]"
+            )
+
+    @staticmethod
+    def format_full_graph(graph: LineageGraph) -> str:
+        """Format complete lineage graph as a Plotly JSON figure.
+
+        Args:
+            graph: LineageGraph with all nodes and edges
+
+        Returns:
+            JSON string representing a Plotly figure specification
+        """
+        PlotlyFormatter._check_plotly_available()
+
+        node_ids = [n.identifier for n in graph.nodes]
+        edge_tuples = [(e.source_node, e.target_node) for e in graph.edges]
+
+        # Build lookup for edge file paths
+        edge_file_paths: dict[tuple[str, str], str] = {}
+        for e in graph.edges:
+            edge_file_paths[(e.source_node, e.target_node)] = e.file_path
+
+        if not node_ids:
+            # Empty graph
+            figure: dict[str, Any] = {
+                "data": [],
+                "layout": {
+                    "title": {"text": "Lineage Graph"},
+                    "showlegend": False,
+                    "xaxis": {"visible": False},
+                    "yaxis": {"visible": False},
+                },
+            }
+            return json.dumps(figure, indent=2)
+
+        positions = _compute_layered_layout(node_ids, edge_tuples)
+
+        # Build edge traces with hover text for file path
+        edge_traces: list[dict[str, Any]] = []
+        edge_annotations: list[dict[str, Any]] = []
+        for src, tgt in edge_tuples:
+            if src in positions and tgt in positions:
+                x0, y0 = positions[src]
+                x1, y1 = positions[tgt]
+                file_path = edge_file_paths.get((src, tgt), "")
+                # Extract just the filename for display
+                file_name = (
+                    file_path.split("/")[-1].split("\\")[-1] if file_path else ""
+                )
+
+                edge_traces.append(
+                    {
+                        "type": "scatter",
+                        "x": [x0, x1, None],
+                        "y": [y0, y1, None],
+                        "mode": "lines",
+                        "line": {"width": 1.5, "color": "#888"},
+                        "hoverinfo": "text",
+                        "hovertext": file_path,
+                        "showlegend": False,
+                    }
+                )
+
+                # Add annotation at midpoint of edge
+                mid_x = (x0 + x1) / 2
+                mid_y = (y0 + y1) / 2
+                edge_annotations.append(
+                    {
+                        "x": mid_x,
+                        "y": mid_y,
+                        "text": file_name,
+                        "showarrow": False,
+                        "font": {"size": 9, "color": "#666"},
+                        "bgcolor": "rgba(255,255,255,0.8)",
+                    }
+                )
+
+        # Build node trace
+        node_x = [positions[n][0] for n in node_ids if n in positions]
+        node_y = [positions[n][1] for n in node_ids if n in positions]
+        node_text = [n for n in node_ids if n in positions]
+
+        node_trace: dict[str, Any] = {
+            "type": "scatter",
+            "x": node_x,
+            "y": node_y,
+            "mode": "markers+text",
+            "text": node_text,
+            "textposition": "top center",
+            "textfont": {"size": 11},
+            "hoverinfo": "text",
+            "marker": {
+                "size": 15,
+                "color": "#6495ED",
+                "line": {"width": 2, "color": "#4169E1"},
+            },
+            "showlegend": False,
+        }
+
+        # Calculate figure dimensions based on graph size
+        min_height = 400
+        height_per_node = 50
+        calculated_height = max(min_height, len(node_ids) * height_per_node)
+
+        figure = {
+            "data": edge_traces + [node_trace],
+            "layout": {
+                "title": {"text": "Lineage Graph"},
+                "showlegend": False,
+                "hovermode": "closest",
+                "xaxis": {"visible": False},
+                "yaxis": {"visible": False},
+                "height": calculated_height,
+                "margin": {"l": 50, "r": 50, "t": 60, "b": 40},
+                "annotations": edge_annotations,
+            },
+        }
+
+        return json.dumps(figure, indent=2)
+
+    @staticmethod
+    def format_query_result(
+        result: LineageQueryResult,
+        graph: Optional[LineageGraph] = None,
+    ) -> str:
+        """Format query result as a Plotly JSON figure with styling.
+
+        The queried column is highlighted in amber, root nodes in teal,
+        and leaf nodes in violet, matching the Mermaid/DOT color scheme.
+
+        Args:
+            result: LineageQueryResult from upstream/downstream query
+            graph: Optional LineageGraph for edge file path labels
+
+        Returns:
+            JSON string representing a Plotly figure specification
+        """
+        PlotlyFormatter._check_plotly_available()
+
+        all_nodes = _collect_query_nodes(result)
+        edges = _collect_query_edges(result)
+
+        # Build edge file path lookup if graph is provided
+        edge_file_paths: dict[tuple[str, str], str] = {}
+        if graph:
+            for e in graph.edges:
+                edge_file_paths[(e.source_node, e.target_node)] = e.file_path
+
+        if not all_nodes:
+            # Should not happen, but handle gracefully
+            figure: dict[str, Any] = {
+                "data": [],
+                "layout": {
+                    "title": {"text": f"Lineage: {result.query_column}"},
+                    "showlegend": False,
+                    "xaxis": {"visible": False},
+                    "yaxis": {"visible": False},
+                },
+            }
+            return json.dumps(figure, indent=2)
+
+        node_list = sorted(all_nodes)
+        edge_list = list(edges)
+        positions = _compute_layered_layout(node_list, edge_list)
+
+        # Build styling lookup
+        root_ids: set[str] = set()
+        leaf_ids: set[str] = set()
+        for node in result.related_columns:
+            if node.is_root:
+                root_ids.add(node.identifier)
+            if node.is_leaf:
+                leaf_ids.add(node.identifier)
+
+        # Determine node colors
+        node_colors: list[str] = []
+        for node in node_list:
+            if node == result.query_column:
+                node_colors.append(QUERIED_FILL)
+            elif node in root_ids:
+                node_colors.append(ROOT_FILL)
+            elif node in leaf_ids:
+                node_colors.append(LEAF_FILL)
+            else:
+                node_colors.append("#6495ED")  # Default blue
+
+        # Build edge traces with optional file path labels
+        edge_traces: list[dict[str, Any]] = []
+        edge_annotations: list[dict[str, Any]] = []
+        for src, tgt in sorted(edges):
+            if src in positions and tgt in positions:
+                x0, y0 = positions[src]
+                x1, y1 = positions[tgt]
+                file_path = edge_file_paths.get((src, tgt), "")
+                file_name = (
+                    file_path.split("/")[-1].split("\\")[-1] if file_path else ""
+                )
+
+                edge_traces.append(
+                    {
+                        "type": "scatter",
+                        "x": [x0, x1, None],
+                        "y": [y0, y1, None],
+                        "mode": "lines",
+                        "line": {"width": 1.5, "color": "#888"},
+                        "hoverinfo": "text" if file_path else "none",
+                        "hovertext": file_path if file_path else None,
+                        "showlegend": False,
+                    }
+                )
+
+                # Add annotation at midpoint of edge if we have file path info
+                if file_name:
+                    mid_x = (x0 + x1) / 2
+                    mid_y = (y0 + y1) / 2
+                    edge_annotations.append(
+                        {
+                            "x": mid_x,
+                            "y": mid_y,
+                            "text": file_name,
+                            "showarrow": False,
+                            "font": {"size": 9, "color": "#666"},
+                            "bgcolor": "rgba(255,255,255,0.8)",
+                        }
+                    )
+
+        # Build node trace
+        node_x = [positions[n][0] for n in node_list if n in positions]
+        node_y = [positions[n][1] for n in node_list if n in positions]
+
+        node_trace: dict[str, Any] = {
+            "type": "scatter",
+            "x": node_x,
+            "y": node_y,
+            "mode": "markers+text",
+            "text": node_list,
+            "textposition": "top center",
+            "textfont": {"size": 11},
+            "hoverinfo": "text",
+            "marker": {
+                "size": 15,
+                "color": node_colors,
+                "line": {"width": 2, "color": "#333"},
+            },
+            "showlegend": False,
+        }
+
+        # Build legend traces (invisible markers for legend display)
+        legend_traces: list[dict[str, Any]] = [
+            {
+                "type": "scatter",
+                "x": [None],
+                "y": [None],
+                "mode": "markers",
+                "marker": {"size": 12, "color": QUERIED_FILL},
+                "name": "Queried Column",
+                "showlegend": True,
+            },
+            {
+                "type": "scatter",
+                "x": [None],
+                "y": [None],
+                "mode": "markers",
+                "marker": {"size": 12, "color": ROOT_FILL},
+                "name": "Root (no upstream)",
+                "showlegend": True,
+            },
+            {
+                "type": "scatter",
+                "x": [None],
+                "y": [None],
+                "mode": "markers",
+                "marker": {"size": 12, "color": LEAF_FILL},
+                "name": "Leaf (no downstream)",
+                "showlegend": True,
+            },
+        ]
+
+        direction_label = "Upstream" if result.direction == "upstream" else "Downstream"
+        title = f"{direction_label} Lineage: {result.query_column}"
+
+        # Calculate figure dimensions based on graph size
+        min_height = 400
+        height_per_node = 50
+        calculated_height = max(min_height, len(node_list) * height_per_node)
+
+        layout: dict[str, Any] = {
+            "title": {"text": title},
+            "showlegend": True,
+            "legend": {"x": 1, "y": 1, "xanchor": "right"},
+            "hovermode": "closest",
+            "xaxis": {"visible": False},
+            "yaxis": {"visible": False},
+            "height": calculated_height,
+            "margin": {"l": 50, "r": 50, "t": 60, "b": 40},
+        }
+
+        # Add edge annotations if we have file path info
+        if edge_annotations:
+            layout["annotations"] = edge_annotations
+
+        figure = {
+            "data": edge_traces + [node_trace] + legend_traces,
+            "layout": layout,
+        }
+
+        return json.dumps(figure, indent=2)