Java SDK for Lineage

The Java SDK provides a fluent API for managing data lineage in OpenMetadata. You can query lineage graphs, create edges between entities with column-level mapping, delete edges, export lineage, and run impact analysis. The fluent entry point is the Lineage class in org.openmetadata.sdk.api.

Lineage in OpenMetadata is a relationship between any two entities. While the examples below use tables and dashboards, the same API works with any entity type (pipelines, topics, ML models, etc.).

Setup

Before using the fluent API, initialize the client:

import org.openmetadata.sdk.api.Lineage;
import org.openmetadata.sdk.client.OpenMetadataClient;
import org.openmetadata.sdk.config.OpenMetadataConfig;

OpenMetadataConfig config = OpenMetadataConfig.builder()
    .serverUrl("http://localhost:8585/api")
    .accessToken("<YOUR-JWT-TOKEN>")
    .build();

OpenMetadataClient client = new OpenMetadataClient(config);

Lineage.setDefaultClient(client);

Querying Lineage

Retrieve the lineage graph for an entity by type and ID:

import org.openmetadata.sdk.api.Lineage;

// Get lineage with default depth (1 upstream, 1 downstream)
Lineage.LineageGraph graph = Lineage.of("table", tableId).fetch();

// Get the raw JSON response
String raw = graph.getRaw();

Custom Depth

Control how many hops upstream and downstream are returned. Use a depth of 3 or less, because the server rejects deeper requests:

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageGraph graph = Lineage.of("table", tableId)
    .upstream(3)
    .downstream(2)
    .fetch();

Or set both directions to the same value:

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageGraph graph = Lineage.of("table", tableId)
    .depth(3)
    .fetch();

Include Deleted Entities

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageGraph graph = Lineage.of("table", tableId)
    .includeDeleted(true)
    .fetch();

Adding Lineage

Use Lineage.connect() to create an edge between two entities:

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageEdge edge = Lineage.connect()
    .from("table", sourceTableId)
    .to("dashboard", dashboardId)
    .withDescription("Dashboard uses data from this table")
    .execute();

Column-Level Lineage

Map specific columns from the source entity to columns in the target entity:

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageEdge edge = Lineage.connect()
    .from("table", sourceTableId)
    .fromColumns("customer_id", "order_date")
    .to("table", targetTableId)
    .toColumns("cust_id", "date")
    .withDescription("ETL transformation")
    .execute();

Each target column in toColumns will be mapped to all columns in fromColumns. The resulting payload includes a columnsLineage array inside lineageDetails.

Pipeline Reference

Associate a pipeline entity that powers the transformation:

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageEdge edge = Lineage.connect()
    .from("table", sourceTableId)
    .to("table", targetTableId)
    .withPipeline("pipeline", pipelineId)
    .withDescription("Daily ETL job")
    .execute();

SQL Query

Attach the SQL query driving the lineage:

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageEdge edge = Lineage.connect()
    .from("table", sourceTableId)
    .to("table", targetTableId)
    .withSqlQuery("INSERT INTO target SELECT id, name FROM source")
    .execute();

Full Example

Combine all options:

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageEdge edge = Lineage.connect()
    .from("table", sourceTableId)
    .fromColumns("customer_id", "order_date")
    .to("table", targetTableId)
    .toColumns("cust_id", "date")
    .withPipeline("pipeline", pipelineId)
    .withDescription("ETL transformation")
    .withSqlQuery("SELECT customer_id, order_date FROM source")
    .execute();

Deleting Lineage

Remove a lineage edge between two entities:

import org.openmetadata.sdk.api.Lineage;

Lineage.disconnect()
    .from("table", sourceTableId)
    .to("dashboard", dashboardId)
    .confirm();

Exporting Lineage

Export the lineage graph for a given entity by its fully qualified name:

import org.openmetadata.sdk.api.Lineage;

String csv = Lineage.export()
    .entity("table", "service.database.schema.my_table")
    .upstream(3)
    .downstream(2)
    .execute();

Impact Analysis

To find the entities affected by a change, fetch the lineage graph in one direction and read the entities from the raw JSON. The nodes array lists every entity in the graph.

Downstream Impact

import org.openmetadata.sdk.api.Lineage;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

Lineage.LineageGraph graph = Lineage.of("table", tableId)
    .upstream(0)
    .downstream(3)
    .fetch();

JsonNode lineage = new ObjectMapper().readTree(graph.getRaw());
for (JsonNode node : lineage.path("nodes")) {
    System.out.println(node.path("type").asText() + ": " + node.path("fullyQualifiedName").asText());
}
System.out.println("Impacted entities: " + lineage.path("nodes").size());

Upstream Impact

import org.openmetadata.sdk.api.Lineage;

Lineage.LineageGraph graph = Lineage.of("dashboard", dashboardId)
    .upstream(3)
    .downstream(0)
    .fetch();

OpenLineage Events

The SDK also supports posting OpenLineage standard events from tools like Spark or Airflow via the OpenLineage fluent API:

import org.openmetadata.sdk.api.Lineage;

import org.openmetadata.sdk.fluent.OpenLineage;

OpenLineage.setDefaultClient(client);

// Post a single run event
String response = OpenLineage.event()
    .withEventType("COMPLETE")
    .withEventTime("2024-01-15T12:00:00Z")
    .withJob("my-etl-job", "my-namespace")
    .withRun("3f2b9c1e-5d4a-4e7b-8a6c-1d2e3f4a5b6c")
    .addInput("source_table", "my-namespace")
    .addOutput("target_table", "my-namespace")
    .send();

Batch Events

import org.openmetadata.sdk.fluent.OpenLineage;

// Build individual events
OpenLineage.RunEventBuilder event1 = OpenLineage.event()
    .withEventType("START")
    .withEventTime("2024-01-15T12:00:00Z")
    .withJob("job-1", "ns")
    .withRun("7a1c2d3e-4b5f-4a6b-9c8d-0e1f2a3b4c5d");

OpenLineage.RunEventBuilder event2 = OpenLineage.event()
    .withEventType("COMPLETE")
    .withEventTime("2024-01-15T12:05:00Z")
    .withJob("job-1", "ns")
    .withRun("7a1c2d3e-4b5f-4a6b-9c8d-0e1f2a3b4c5d");

// Send as a batch
String response = OpenLineage.batch()
    .addEvent(event1)
    .addEvent(event2)
    .send();

Static API

For simpler use cases, the LineageAPI class in org.openmetadata.sdk.api provides static methods that wrap the underlying HTTP calls. They use a shared client, which you set up once with OpenMetadata.initialize:

import java.util.Map;
import org.openmetadata.sdk.api.LineageAPI;
import org.openmetadata.sdk.client.OpenMetadata;

OpenMetadata.initialize("http://localhost:8585/api", "<YOUR-JWT-TOKEN>");

// Get lineage by entity FQN
String lineage = LineageAPI.getLineage("table/name/service.db.schema.table");

// Get lineage with depth
String lineageWithDepth = LineageAPI.getLineage("table/name/service.db.schema.table", "3", "2");

// Get lineage by entity type and ID
String lineageById = LineageAPI.getEntityLineage("table", tableId);

// Add lineage (pass a Map matching the AddLineage JSON schema)
Map<String, Object> lineageRequestMap = Map.of("edge", Map.of(
    "fromEntity", Map.of("id", sourceTableId, "type", "table"),
    "toEntity", Map.of("id", targetTableId, "type", "table")));
String result = LineageAPI.addLineage(lineageRequestMap);

// Delete lineage
String deleted = LineageAPI.deleteLineage("table:" + sourceTableId, "dashboard:" + dashboardId);

// Export lineage
String csv = LineageAPI.exportLineage("service.db.schema.table", "table", "3", "2");

Async Variants

All static methods have CompletableFuture-based async variants:

import java.util.concurrent.CompletableFuture;
import org.openmetadata.sdk.api.LineageAPI;

CompletableFuture<String> future = LineageAPI.getLineageAsync("table/name/service.db.schema.table");
future.thenAccept(lineage -> System.out.println("Lineage: " + lineage));

CompletableFuture<String> addFuture = LineageAPI.addLineageAsync(lineageRequestMap);
CompletableFuture<String> deleteFuture = LineageAPI.deleteLineageAsync(
    "table:" + sourceTableId, "dashboard:" + dashboardId);

API Reference

Data Assets

Collaboration

AI SDK

SDK

Discovery

Lineage

Data Contracts

Teams And Users

Data Governance

Data Quality

Alerts

Incidents

Main Concepts

Java SDK for Lineage

Java SDK for Lineage

Setup

Querying Lineage

Custom Depth

Include Deleted Entities

Adding Lineage

Column-Level Lineage

Pipeline Reference

SQL Query

Full Example

Deleting Lineage

Exporting Lineage

Impact Analysis

Downstream Impact

Upstream Impact

OpenLineage Events

Batch Events

Static API

Async Variants

​Java SDK for Lineage

​Setup

​Querying Lineage

​Custom Depth

​Include Deleted Entities

​Adding Lineage

​Column-Level Lineage

​Pipeline Reference

​SQL Query

​Full Example

​Deleting Lineage

​Exporting Lineage

​Impact Analysis

​Downstream Impact

​Upstream Impact

​OpenLineage Events

​Batch Events

​Static API

​Async Variants

Java SDK for Lineage

Setup

Querying Lineage

Custom Depth

Include Deleted Entities

Adding Lineage

Column-Level Lineage

Pipeline Reference

SQL Query

Full Example

Deleting Lineage

Exporting Lineage

Impact Analysis

Downstream Impact

Upstream Impact

OpenLineage Events

Batch Events

Static API

Async Variants