Get Lineage

Retrieve the lineage graph for an entity by ID or fully qualified name

GET /v1/lineage/{entityType}/{id}

GET /v1/lineage/{entityType}/{id}

Python

from metadata.generated.schema.entity.data.table import Table
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)

server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(
        jwtToken="<YOUR-JWT-TOKEN>"
    ),
)
metadata = OpenMetadata(server_config)

# Get lineage by fully qualified name
lineage = metadata.get_lineage_by_name(
    entity=Table,
    fqn="sample_data.ecommerce_db.shopify.dim_customer",
    up_depth=1,
    down_depth=1,
)

print(f"Entity: {lineage['entity']['fullyQualifiedName']}")
print(f"Upstream edges: {len(lineage.get('upstreamEdges', []))}")
print(f"Downstream edges: {len(lineage.get('downstreamEdges', []))}")

# Get lineage by ID
lineage = metadata.get_lineage_by_id(
    entity=Table,
    entity_id="455e3d9d-dbbf-455e-b3be-7191daa825f3",
    up_depth=3,
    down_depth=2,
)

Response

{
  "entity": {
    "id": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
    "type": "table",
    "name": "dim_customer",
    "fullyQualifiedName": "sample_data.ecommerce_db.shopify.dim_customer",
    "deleted": false,
    "href": "http://localhost:8585/api/v1/tables/455e3d9d-dbbf-455e-b3be-7191daa825f3"
  },
  "nodes": [
    {
      "id": "800caa0f-a149-48d2-a0ce-6ca84501767e",
      "type": "table",
      "name": "raw_customer",
      "fullyQualifiedName": "sample_data.ecommerce_db.shopify.raw_customer",
      "deleted": false,
      "href": "http://localhost:8585/api/v1/tables/800caa0f-a149-48d2-a0ce-6ca84501767e"
    },
    {
      "id": "c3d4e5f6-a1b2-7890-abcd-ef1234567890",
      "type": "dashboard",
      "name": "customer_dashboard",
      "fullyQualifiedName": "sample_superset.customer_dashboard",
      "deleted": false,
      "href": "http://localhost:8585/api/v1/dashboards/c3d4e5f6-a1b2-7890-abcd-ef1234567890"
    }
  ],
  "upstreamEdges": [
    {
      "fromEntity": "800caa0f-a149-48d2-a0ce-6ca84501767e",
      "toEntity": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
      "lineageDetails": {
        "sqlQuery": "INSERT INTO dim_customer SELECT id, name FROM raw_customer",
        "columnsLineage": [
          {
            "fromColumns": [
              "sample_data.ecommerce_db.shopify.raw_customer.id"
            ],
            "toColumn": "sample_data.ecommerce_db.shopify.dim_customer.customer_id"
          }
        ]
      }
    }
  ],
  "downstreamEdges": [
    {
      "fromEntity": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
      "toEntity": "c3d4e5f6-a1b2-7890-abcd-ef1234567890"
    }
  ]
}

​

Get Lineage

Retrieve the lineage graph for an entity, including upstream and downstream edges. You can query by entity ID or fully qualified name.

The Python examples on this page use the original client (metadata.ingestion.ometa.ometa_api.OpenMetadata) because SDK 2.0 (metadata.sdk) doesn’t include lineage operations. For more information, see Which Python SDK Should I Use?.

​

Get by Entity Type and ID

entityType · string · required

Type of the entity. Options: table, dashboard, pipeline, topic, mlmodel, container, searchIndex, storedProcedure, dashboardDataModel, apiEndpoint.

id · string · required

UUID of the entity to retrieve lineage for.

upstreamDepth · integer · default: "1"

Number of hops to traverse upstream (min: 0, max: 3).

downstreamDepth · integer · default: "1"

Number of hops to traverse downstream (min: 0, max: 3).

​

Get by Entity Type and FQN

Use GET /v1/lineage/{entityType}/name/{fqn} to retrieve lineage by fully qualified name.

entityType · string · required

Type of the entity. Options: table, dashboard, pipeline, topic, mlmodel, container, searchIndex, storedProcedure, dashboardDataModel, apiEndpoint.

fqn · string · required

Fully qualified name of the entity (e.g., sample_data.ecommerce_db.shopify.dim_customer).

upstreamDepth · integer · default: "1"

Number of hops to traverse upstream (min: 0, max: 3).

downstreamDepth · integer · default: "1"

Number of hops to traverse downstream (min: 0, max: 3).

GET /v1/lineage/{entityType}/{id}

Python

from metadata.generated.schema.entity.data.table import Table
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)

server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(
        jwtToken="<YOUR-JWT-TOKEN>"
    ),
)
metadata = OpenMetadata(server_config)

# Get lineage by fully qualified name
lineage = metadata.get_lineage_by_name(
    entity=Table,
    fqn="sample_data.ecommerce_db.shopify.dim_customer",
    up_depth=1,
    down_depth=1,
)

print(f"Entity: {lineage['entity']['fullyQualifiedName']}")
print(f"Upstream edges: {len(lineage.get('upstreamEdges', []))}")
print(f"Downstream edges: {len(lineage.get('downstreamEdges', []))}")

# Get lineage by ID
lineage = metadata.get_lineage_by_id(
    entity=Table,
    entity_id="455e3d9d-dbbf-455e-b3be-7191daa825f3",
    up_depth=3,
    down_depth=2,
)

Response

{
  "entity": {
    "id": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
    "type": "table",
    "name": "dim_customer",
    "fullyQualifiedName": "sample_data.ecommerce_db.shopify.dim_customer",
    "deleted": false,
    "href": "http://localhost:8585/api/v1/tables/455e3d9d-dbbf-455e-b3be-7191daa825f3"
  },
  "nodes": [
    {
      "id": "800caa0f-a149-48d2-a0ce-6ca84501767e",
      "type": "table",
      "name": "raw_customer",
      "fullyQualifiedName": "sample_data.ecommerce_db.shopify.raw_customer",
      "deleted": false,
      "href": "http://localhost:8585/api/v1/tables/800caa0f-a149-48d2-a0ce-6ca84501767e"
    },
    {
      "id": "c3d4e5f6-a1b2-7890-abcd-ef1234567890",
      "type": "dashboard",
      "name": "customer_dashboard",
      "fullyQualifiedName": "sample_superset.customer_dashboard",
      "deleted": false,
      "href": "http://localhost:8585/api/v1/dashboards/c3d4e5f6-a1b2-7890-abcd-ef1234567890"
    }
  ],
  "upstreamEdges": [
    {
      "fromEntity": "800caa0f-a149-48d2-a0ce-6ca84501767e",
      "toEntity": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
      "lineageDetails": {
        "sqlQuery": "INSERT INTO dim_customer SELECT id, name FROM raw_customer",
        "columnsLineage": [
          {
            "fromColumns": [
              "sample_data.ecommerce_db.shopify.raw_customer.id"
            ],
            "toColumn": "sample_data.ecommerce_db.shopify.dim_customer.customer_id"
          }
        ]
      }
    }
  ],
  "downstreamEdges": [
    {
      "fromEntity": "455e3d9d-dbbf-455e-b3be-7191daa825f3",
      "toEntity": "c3d4e5f6-a1b2-7890-abcd-ef1234567890"
    }
  ]
}

---

​

Returns

Returns the lineage graph centered on the requested entity, including upstream and downstream edges up to the specified depth.

​

Response

entity · object

The entity reference for the node at the center of the lineage graph.

Show properties

id · string

Unique identifier (UUID).

type · string

Entity type (e.g., table, dashboard, pipeline).

name · string

Entity name.

fullyQualifiedName · string

Fully qualified name of the entity.

deleted · boolean

Whether the entity has been soft-deleted.

nodes · array

List of entity references for all nodes in the lineage graph (excluding the center entity).

upstreamEdges · array

Edges pointing into the center entity (data sources).

Show properties

fromEntity · string

UUID of the source entity.

toEntity · string

UUID of the destination entity.

lineageDetails · object

Optional details about the lineage edge.

Show properties

sqlQuery · string

SQL query driving the transformation.

columnsLineage · array

Column-level lineage mappings.

Show properties

fromColumns · array

List of source column FQNs.

toColumn · string

Destination column FQN.

pipeline · object

Entity reference for the pipeline powering the transformation.

downstreamEdges · array

Edges pointing away from the center entity (data destinations). Same structure as upstreamEdges.

---

​

Error Handling

Code	Error Type	Description
401	UNAUTHORIZED	Invalid or missing authentication token
403	FORBIDDEN	User lacks permission to view lineage
404	NOT_FOUND	Entity with given ID or FQN does not exist