Skip to main content

​
Overview

Graph lineage records how every meaningful change to the knowledge graph was made — which document, data source, enrichment rule, or manual review produced each property update or relationship. Each change is stored as a :LineageRecord node in Neo4j, linked to the affected entity via :HAS_LINEAGE. Lineage is additive: legacy source lists on nodes continue to work during rollout. Lineage is not included in routine AI context or graph visualizations. It is available on demand in the graph explorer, provenance panel, and read API.

​
What gets recorded

Each record includes:
  • Operation — node_created, node_updated, relationship_created, etc.
  • Changes — property-level {property, old, new} transitions
  • Source metadata — path, data source name, rule name, job id
  • Model — LLM model name when applicable (ingestion, enrichment)
  • Reviewer — email address for manual match-review actions
  • Timestamp — when the write occurred
Document-sourced records may link to the :Document node via :DERIVED_FROM for one-click file access.

​
Viewing lineage in the UI

​
Graph explorer (provenance)

When exploring entities cited in chat:
  1. Open the provenance graph explorer for a response
  2. Select an entity node
  3. Scroll to the Graph Lineage section in the inspector
The timeline shows operations newest-first, with source links, model name, reviewer (if manual), and property changes. Relationship operations show type and from → to endpoints.

​
Provenance panel — View lineage

In the provenance entity cards, click View lineage to open the graph explorer focused on that entity’s lineage history.

​
Chat — asking about origin

Assistants can call the get_entity_lineage tool when you ask where a fact came from (e.g. “How do we know this company’s revenue?”). Lineage is never injected proactively into every response.

​
Enrichment jobs and Postgres audit

Enrichment rules write graph lineage for each successful apply. The Django EnrichmentResult row also stores an optional lineage_record_id linking to the graph record for admin cross-reference. See Enrichment Rules for running jobs; open a job’s results to see which nodes were updated and the linked lineage id when present.

​
Read API

Authenticated REST endpoints (prefix /api/graph-lineage/): Relationship lineage appears when querying either endpoint node (from_id / to_id matching).

​
Matched document entities

When document ingestion matches an existing node and only adds the file to source (no new attributes), a node-level lineage record is not created. Relationship lineage from the same ingest still records links to related entities (e.g. Contract → Company).

​
Limitations (v1)

  • No automatic backfill for data ingested before lineage shipped
  • relationship_deleted not recorded (no delete paths wired yet)
  • Legacy client UI does not include lineage; use the current admin/chat UI (client-cn)
  • Deprecation of n.source in favor of lineage-only provenance is a follow-up ticket