Relationships and traversal

An edge is accepted only when it satisfies its relationship contract and the current graph state.

To explore existing relationships in the dashboard, start with Entity 360 and the lineage walkthrough. Use contexts and lineage when interpreting environment-specific results.

Edge CRUD

POST /edges
GET  /edges
GET  /edges/{edge_id}
PUT  /edges/{edge_id}
PATCH /edges/{edge_id}
DELETE /edges/{edge_id}
GET  /entities/{entity_id}/edges

Edge fields include relationship type, context, entity endpoints, optional field endpoints, evidence, metadata, provenance, confidence, lifecycle and validity times.

Validation order

VegaGraph verifies:

1. all IDs belong to the scoped workspace;
2. endpoints exist and are visible;
3. source and target types/categories satisfy the relationship type;
4. field endpoints belong to the corresponding endpoint entities and are permitted;
5. context boundaries are legal;
6. cardinality is not violated;
7. an acyclic relationship would remain acyclic;
8. exact duplicate identity is not created.

A syntactically valid JSON edge can still fail these semantic checks.

Direction

Direction follows the relationship type's source and target contract. Forward and inverse labels are presentation metadata; clients should retain the actual direction when asking lineage or impact questions.

Context behavior

A canonical edge connects canonical endpoints. A context-specific edge can connect canonical endpoints or endpoints from the same selected context. It cannot mix unrelated environment-specific endpoints.

Context-aware reads combine canonical, inherited and direct edges according to the selected lens and relationship contract. Surface each result's origin to users.

Traverse

GET /entities/{entity_id}/traverse?direction=outbound&max_depth=3&context_id={context_id}

Use inbound, outbound or supported bidirectional behavior according to the API schema. Restrict relationship types/categories when asking a specific question. Depth and result size are bounded.

Traversal returns paths/vertices/edges required to explain the result. It does not imply that every reachable object should be loaded into a single visualization.

Hierarchy

GET /entities/{entity_id}/hierarchy/path
GET /entities/{entity_id}/hierarchy/children

Hierarchy endpoints use structural relationship semantics and are optimized for breadcrumbs and child lists. They are preferable to a general traversal for those views.

Field lineage

GET /field-refs/{field_ref_id}/lineage

Field lineage follows permitted field-to-field or field-to-entity relationships while retaining parent entity context. Use the immutable transformation/pipeline version and run identity in evidence when VegaFlow publishes lineage.

Impact and dependency views

Friendly endpoints such as KPI impact, KPI lineage and service dependencies apply product-specific relationship filters over the same governed graph. Use them for common questions and general traversal for custom relationship paths.