Skip to content

feat(kg): support optional label property as display name for graph nodes#2757

Closed
4ST-499 wants to merge 1 commit intoHKUDS:mainfrom
4ST-499:feature/graph-node-label-property
Closed

feat(kg): support optional label property as display name for graph nodes#2757
4ST-499 wants to merge 1 commit intoHKUDS:mainfrom
4ST-499:feature/graph-node-label-property

Conversation

@4ST-499
Copy link
Copy Markdown

@4ST-499 4ST-499 commented Mar 8, 2026

Summary

  • When a graph node has a label property, all graph query endpoints (get_all_labels, search_labels, get_popular_labels, get_knowledge_graph) now use it as the display name instead of the raw entity_id
  • Nodes without a label property fall back to entity_id — fully backward-compatible, zero behavior change for existing users
  • Covers all 5 storage backends: NetworkX, Neo4j, PostgreSQL/AGE, MongoDB, Memgraph

Motivation

Currently KnowledgeGraphNode(labels=[str(node)]) uses the raw node ID as display text. This works when IDs are human-readable strings like "ELON MUSK", but breaks for workflows that use UUIDs, hashes, or other non-human-readable node keys. Adding an optional label property decouples display name from graph identity.

Changes

File Change
networkx_impl.py .get("label", entity_id) fallback in 4 query methods
neo4j_impl.py COALESCE(n.label, n.entity_id) in 7 Cypher queries
postgres_impl.py COALESCE in Cypher + agtype access + Python .get() fallbacks
mongo_impl.py $ifNull in aggregation pipelines, $or regex for search, $lookup for popular labels
memgraph_impl.py COALESCE(n.label, n.entity_id) in 4 Cypher queries
utils_graph.py acreate_entity() forwards label from entity_data to node properties

Test plan

  • 6 offline tests (NetworkX): insert nodes with/without label, verify all 4 query endpoints return correct display names
  • 5 integration tests (PostgreSQL/AGE): same coverage against live AGE database
  • Backward compatibility: nodes without label property behave identically to before

…odes

When a node has a `label` property, it is used as the display name
instead of the raw entity_id in all graph query endpoints:
get_all_labels, search_labels, get_popular_labels, get_knowledge_graph.

This is useful when node IDs are UUIDs or hashes rather than
human-readable strings. Nodes without a label property fall back
to entity_id (fully backward-compatible).

Changes across all storage backends:
- NetworkXStorage, Neo4JStorage, PGGraphStorage, MongoGraphStorage,
  MemgraphStorage: use label property with entity_id fallback
- acreate_entity: forward label from entity_data to graph node
- Add offline tests (NetworkX) and PG/AGE integration tests
@danielaskdd
Copy link
Copy Markdown
Collaborator

The label concept is obsolete in the LightRAG backend and is no longer stored. Entities
generated in the pipeline and subsequent merging processes do not include label fields.
The labels array returned to the frontend exists solely for backward compatibility.

The frontend's reliance on labels stems from early UI designs and Neo4j's specific
architecture. In LightRAG, Neo4j labels are now repurposed for workspace isolation, meaning
the actual storage labels are not exposed to the frontend.

Based on this, we recommend hiding labels in the frontend UI rather than attempting to
populate this attribute from the backend.

Based on the analysis above, unfortunately this PR will not be merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants