Skip to content

Refactor: Enhanced Entity Merging with Chunk Tracking #2266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danielaskdd merged 13 commits into from
Oct 27, 2025
Merged

Refactor: Enhanced Entity Merging with Chunk Tracking #2266

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
3855937
Fix entity merging to include target entity relationships
danielaskdd Oct 26, 2025
ab32456
Refactor entity merging with unified attribute merge function
danielaskdd Oct 26, 2025
a25003c
Fix relation deduplication logic and standardize log message prefixes
danielaskdd Oct 26, 2025
2c09adb
Add chunk tracking support to entity merge functionality
danielaskdd Oct 26, 2025
8dfd3bf
Replace global graph DB lock with fine-grained keyed locking
danielaskdd Oct 26, 2025
25f829e
Enable editing of entity_type field in node properties
danielaskdd Oct 27, 2025
94f24a6
Bump API version to 0246
danielaskdd Oct 27, 2025
411e92e
Fix vector deletion logging to show actual deleted count
danielaskdd Oct 27, 2025
11a1631
Refactor entity edit and merge functions to support merge-on-rename
danielaskdd Oct 27, 2025
97034f0
Add allow_merge parameter to entity update API endpoint
danielaskdd Oct 27, 2025
5155edd
feat: Improve entity merge and edit UX
danielaskdd Oct 27, 2025
ea006bd
Fix entity update logic to handle renaming operations
danielaskdd Oct 27, 2025
b32b2e8
Refactor merge dialog and improve search history sync
danielaskdd Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion lightrag/api/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__api_version__ = "0245"
__api_version__ = "0246"
165 changes: 161 additions & 4 deletions lightrag/api/routers/graph_routes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ class EntityUpdateRequest(BaseModel):
entity_name: str
updated_data: Dict[str, Any]
allow_rename: bool = False
allow_merge: bool = False


class RelationUpdateRequest(BaseModel):
Expand Down Expand Up @@ -221,22 +222,178 @@ async def update_entity(request: EntityUpdateRequest):
"""
Update an entity's properties in the knowledge graph

This endpoint allows updating entity properties, including renaming entities.
When renaming to an existing entity name, the behavior depends on allow_merge:

Args:
request (EntityUpdateRequest): Request containing entity name, updated data, and rename flag
request (EntityUpdateRequest): Request containing:
- entity_name (str): Name of the entity to update
- updated_data (Dict[str, Any]): Dictionary of properties to update
- allow_rename (bool): Whether to allow entity renaming (default: False)
- allow_merge (bool): Whether to merge into existing entity when renaming
causes name conflict (default: False)

Returns:
Dict: Updated entity information
Dict with the following structure:
{
"status": "success",
"message": "Entity updated successfully" | "Entity merged successfully into 'target_name'",
"data": {
"entity_name": str, # Final entity name
"description": str, # Entity description
"entity_type": str, # Entity type
"source_id": str, # Source chunk IDs
... # Other entity properties
},
"operation_summary": {
"merged": bool, # Whether entity was merged into another
"merge_status": str, # "success" | "failed" | "not_attempted"
"merge_error": str | None, # Error message if merge failed
"operation_status": str, # "success" | "partial_success" | "failure"
"target_entity": str | None, # Target entity name if renaming/merging
"final_entity": str, # Final entity name after operation
"renamed": bool # Whether entity was renamed
}
}

operation_status values explained:
- "success": All operations completed successfully
* For simple updates: entity properties updated
* For renames: entity renamed successfully
* For merges: non-name updates applied AND merge completed

- "partial_success": Update succeeded but merge failed
* Non-name property updates were applied successfully
* Merge operation failed (entity not merged)
* Original entity still exists with updated properties
* Use merge_error for failure details

- "failure": Operation failed completely
* If merge_status == "failed": Merge attempted but both update and merge failed
* If merge_status == "not_attempted": Regular update failed
* No changes were applied to the entity

merge_status values explained:
- "success": Entity successfully merged into target entity
- "failed": Merge operation was attempted but failed
- "not_attempted": No merge was attempted (normal update/rename)

Behavior when renaming to an existing entity:
- If allow_merge=False: Raises ValueError with 400 status (default behavior)
- If allow_merge=True: Automatically merges the source entity into the existing target entity,
preserving all relationships and applying non-name updates first

Example Request (simple update):
POST /graph/entity/edit
{
"entity_name": "Tesla",
"updated_data": {"description": "Updated description"},
"allow_rename": false,
"allow_merge": false
}

Example Response (simple update success):
{
"status": "success",
"message": "Entity updated successfully",
"data": { ... },
"operation_summary": {
"merged": false,
"merge_status": "not_attempted",
"merge_error": null,
"operation_status": "success",
"target_entity": null,
"final_entity": "Tesla",
"renamed": false
}
}

Example Request (rename with auto-merge):
POST /graph/entity/edit
{
"entity_name": "Elon Msk",
"updated_data": {
"entity_name": "Elon Musk",
"description": "Corrected description"
},
"allow_rename": true,
"allow_merge": true
}

Example Response (merge success):
{
"status": "success",
"message": "Entity merged successfully into 'Elon Musk'",
"data": { ... },
"operation_summary": {
"merged": true,
"merge_status": "success",
"merge_error": null,
"operation_status": "success",
"target_entity": "Elon Musk",
"final_entity": "Elon Musk",
"renamed": true
}
}

Example Response (partial success - update succeeded but merge failed):
{
"status": "success",
"message": "Entity updated successfully",
"data": { ... }, # Data reflects updated "Elon Msk" entity
"operation_summary": {
"merged": false,
"merge_status": "failed",
"merge_error": "Target entity locked by another operation",
"operation_status": "partial_success",
"target_entity": "Elon Musk",
"final_entity": "Elon Msk", # Original entity still exists
"renamed": true
}
}
"""
try:
result = await rag.aedit_entity(
entity_name=request.entity_name,
updated_data=request.updated_data,
allow_rename=request.allow_rename,
allow_merge=request.allow_merge,
)

# Extract operation_summary from result, with fallback for backward compatibility
operation_summary = result.get(
"operation_summary",
{
"merged": False,
"merge_status": "not_attempted",
"merge_error": None,
"operation_status": "success",
"target_entity": None,
"final_entity": request.updated_data.get(
"entity_name", request.entity_name
),
"renamed": request.updated_data.get(
"entity_name", request.entity_name
)
!= request.entity_name,
},
)

# Separate entity data from operation_summary for clean response
entity_data = dict(result)
entity_data.pop("operation_summary", None)

# Generate appropriate response message based on merge status
response_message = (
f"Entity merged successfully into '{operation_summary['final_entity']}'"
if operation_summary.get("merged")
else "Entity updated successfully"
)
return {
"status": "success",
"message": "Entity updated successfully",
"data": result,
"message": response_message,
"data": entity_data,
"operation_summary": operation_summary,
}
except ValueError as ve:
logger.error(
Expand Down
2 changes: 1 addition & 1 deletion lightrag/constants.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
"NaturalObject",
]

# Separator for graph fields
# Separator for: description, source_id and relation-key fields(Can not be changed after data inserted)
GRAPH_FIELD_SEP = "<SEP>"

# Query and retrieval configuration defaults
Expand Down
10 changes: 9 additions & 1 deletion lightrag/kg/nano_vector_db_impl.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,9 +184,17 @@ async def delete(self, ids: list[str]):
"""
try:
client = await self._get_client()
# Record count before deletion
before_count = len(client)

client.delete(ids)

# Calculate actual deleted count
after_count = len(client)
deleted_count = before_count - after_count

logger.debug(
f"[{self.workspace}] Successfully deleted {len(ids)} vectors from {self.namespace}"
f"[{self.workspace}] Successfully deleted {deleted_count} vectors from {self.namespace}"
)
except Exception as e:
logger.error(
Expand Down
18 changes: 15 additions & 3 deletions lightrag/lightrag.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3577,7 +3577,11 @@ async def get_relation_info(
)

async def aedit_entity(
self, entity_name: str, updated_data: dict[str, str], allow_rename: bool = True
self,
entity_name: str,
updated_data: dict[str, str],
allow_rename: bool = True,
allow_merge: bool = False,
) -> dict[str, Any]:
"""Asynchronously edit entity information.

Expand All @@ -3588,6 +3592,7 @@ async def aedit_entity(
entity_name: Name of the entity to edit
updated_data: Dictionary containing updated attributes, e.g. {"description": "new description", "entity_type": "new type"}
allow_rename: Whether to allow entity renaming, defaults to True
allow_merge: Whether to merge into an existing entity when renaming to an existing name

Returns:
Dictionary containing updated entity information
Expand All @@ -3601,16 +3606,21 @@ async def aedit_entity(
entity_name,
updated_data,
allow_rename,
allow_merge,
self.entity_chunks,
self.relation_chunks,
)

def edit_entity(
self, entity_name: str, updated_data: dict[str, str], allow_rename: bool = True
self,
entity_name: str,
updated_data: dict[str, str],
allow_rename: bool = True,
allow_merge: bool = False,
) -> dict[str, Any]:
loop = always_get_an_event_loop()
return loop.run_until_complete(
self.aedit_entity(entity_name, updated_data, allow_rename)
self.aedit_entity(entity_name, updated_data, allow_rename, allow_merge)
)

async def aedit_relation(
Expand Down Expand Up @@ -3750,6 +3760,8 @@ async def amerge_entities(
target_entity,
merge_strategy,
target_entity_data,
self.entity_chunks,
self.relation_chunks,
)

def merge_entities(
Expand Down
Loading