Lineage Visualization

The LineageVisualizationController provides APIs for graph rendering, impact analysis, path finding, and lineage export in multiple formats. It powers the lineage UI in the Data Workbench.

Graph Visualization

Full Graph Request

Generate a lineage graph with full configuration:

POST /api/v1/lineage/visualization/graph

curl -X POST "http://localhost:8086/api/v1/lineage/visualization/graph" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "BOTH",
    "maxDepth": 5,
    "includeColumnLineage": true,
    "entityTypeFilter": ["TABLE", "VIEW", "PIPELINE"],
    "lineageTypeFilter": ["DIRECT", "DERIVED"]
  }'

Simple Graph Request

Quick graph generation with default parameters:

GET /api/v1/lineage/visualization/graph/{entityId}?direction=BOTH&maxDepth=5&includeColumnLineage=false

curl "http://localhost:8086/api/v1/lineage/visualization/graph/550e8400-e29b-41d4-a716-446655440001?direction=BOTH&maxDepth=5&includeColumnLineage=true" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

Required Roles

Graph visualization endpoints require one of:

ADMIN
CATALOG_VIEWER
DATA_STEWARD

Impact Analysis

Analyze the downstream impact of a proposed change to understand which assets would be affected.

Full Impact Analysis

POST /api/v1/lineage/visualization/impact-analysis

curl -X POST "http://localhost:8086/api/v1/lineage/visualization/impact-analysis" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440001",
    "changeType": "SCHEMA_CHANGE",
    "maxDepth": 10,
    "includeIndirectImpacts": true,
    "affectedColumns": ["customer_id", "order_date"]
  }'

Response

{
  "entityId": "550e8400-e29b-41d4-a716-446655440001",
  "changeType": "SCHEMA_CHANGE",
  "impactedEntities": [
    {
      "entityId": "tbl-dim-orders",
      "entityName": "analytics.dim_orders",
      "entityType": "TABLE",
      "impactType": "DIRECT",
      "depth": 1,
      "affectedColumns": ["customer_id", "order_date"],
      "severity": "HIGH",
      "owner": "data-engineering@company.com"
    },
    {
      "entityId": "tbl-monthly-sales",
      "entityName": "reporting.monthly_sales",
      "entityType": "TABLE",
      "impactType": "INDIRECT",
      "depth": 2,
      "affectedColumns": ["order_date"],
      "severity": "MEDIUM"
    },
    {
      "entityId": "dashboard-revenue",
      "entityName": "Revenue Dashboard",
      "entityType": "DASHBOARD",
      "impactType": "INDIRECT",
      "depth": 3,
      "severity": "LOW"
    }
  ],
  "summary": {
    "totalImpacted": 3,
    "directImpacts": 1,
    "indirectImpacts": 2,
    "highSeverity": 1,
    "mediumSeverity": 1,
    "lowSeverity": 1
  }
}

Change Types

Change Type	Description
`SCHEMA_CHANGE`	Column addition, removal, or type change
`DATA_CHANGE`	Data values or distributions change
`DEPRECATION`	Entity being deprecated or removed
`OWNERSHIP_CHANGE`	Entity ownership transfer

Simple Impact Analysis

GET /api/v1/lineage/visualization/impact-analysis/{entityId}?changeType=SCHEMA_CHANGE&maxDepth=10

curl "http://localhost:8086/api/v1/lineage/visualization/impact-analysis/550e8400-e29b-41d4-a716-446655440001?changeType=DEPRECATION&maxDepth=10" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

Required Roles

Impact analysis requires one of:

ADMIN
DATA_STEWARD
DATA_ENGINEER

Path Finding

Find all paths between two entities through the lineage graph.

Advanced Path Finding

POST /api/v1/lineage/visualization/paths

curl -X POST "http://localhost:8086/api/v1/lineage/visualization/paths" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "sourceEntityId": "550e8400-e29b-41d4-a716-446655440001",
    "targetEntityId": "550e8400-e29b-41d4-a716-446655440002",
    "maxPaths": 3,
    "maxPathLength": 10
  }'

Simple Path Finding

GET /api/v1/lineage/visualization/paths/{sourceId}/{targetId}?maxPaths=3

curl "http://localhost:8086/api/v1/lineage/visualization/paths/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440002?maxPaths=5" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

Column-Level Lineage Visualization

Full Column Lineage Request

POST /api/v1/lineage/visualization/columns

curl -X POST "http://localhost:8086/api/v1/lineage/visualization/columns" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "tableId": "550e8400-e29b-41d4-a716-446655440001",
    "columnName": "revenue",
    "direction": "BOTH",
    "maxDepth": 3
  }'

Simple Column Lineage

GET /api/v1/lineage/visualization/columns/{tableId}?columnName=revenue

curl "http://localhost:8086/api/v1/lineage/visualization/columns/550e8400-e29b-41d4-a716-446655440001?columnName=revenue" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

Export Lineage

Export the lineage graph in multiple formats for external analysis or documentation.

POST /api/v1/lineage/visualization/export

Supported Formats

Format	Description
`JSON`	Native JSON graph format
`CSV`	Comma-separated edge list
`GRAPHML`	GraphML XML format for graph visualization tools
`DOT`	Graphviz DOT format for diagram generation

Export as CSV

curl -X POST "http://localhost:8086/api/v1/lineage/visualization/export" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440001",
    "direction": "BOTH",
    "maxDepth": 5,
    "includeColumnLineage": false,
    "format": "CSV"
  }'

CSV Response

source_id,source_name,target_id,target_name,lineage_type
tbl-raw-orders,raw.orders,tbl-dim-orders,analytics.dim_orders,DIRECT
tbl-dim-orders,analytics.dim_orders,tbl-monthly-sales,reporting.monthly_sales,DERIVED

Export as DOT (Graphviz)

curl -X POST "http://localhost:8086/api/v1/lineage/visualization/export" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "entityId": "...", "format": "DOT", "direction": "BOTH", "maxDepth": 3 }'

DOT Response

digraph lineage {
  rankdir=LR;
  node [shape=box];

  "tbl-raw-orders" [label="raw.orders\n(TABLE)"];
  "tbl-dim-orders" [label="analytics.dim_orders\n(TABLE)"];

  "tbl-raw-orders" -> "tbl-dim-orders" [label="DIRECT"];
}

Export as GraphML

curl -X POST "http://localhost:8086/api/v1/lineage/visualization/export" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "entityId": "...", "format": "GRAPHML", "direction": "DOWNSTREAM", "maxDepth": 5 }'

Required Roles

Export requires ADMIN or DATA_STEWARD role.

Source Reference

Component	File
Graph visualization	`LineageVisualizationController.java` -- `getLineageGraph()`
Impact analysis	`LineageVisualizationController.java` -- `analyzeImpact()`
Path finding	`LineageVisualizationController.java` -- `findPaths()`
Column lineage viz	`LineageVisualizationController.java` -- `getColumnLineage()`
Export	`LineageVisualizationController.java` -- `exportLineage()`
Visualization service	`LineageVisualizationService.java`
Impact analysis service	`VisualizationImpactAnalysisService.java`

Column-Level Lineage Creating Lineage