How to Implement Document Deletion with Automatic Knowledge Graph Regeneration in LightRAG

LightRAG removes documents by deleting their vector embeddings and graph entities via the delete_document method, then automatically triggers rebuild_graph to regenerate the knowledge graph from remaining documents and restore relationship integrity.

LightRAG treats every upload as a composite of text chunks, vector embeddings, and knowledge-graph entities/relations. Removing a document requires purging these artifacts from storage backends (Qdrant, Postgres, Neo4j) and rebuilding the graph to eliminate stale cross-document relationships. This implementation leverages the FastAPI server and core library modules from the HKUDS/LightRAG repository.

Architecture of Document Deletion

LightRAG coordinates deletion across multiple subsystems to maintain data consistency. The workflow spans HTTP handlers, background task queues, vector stores, and graph database implementations.

The primary components include:

• lightrag/api/routers/document_routes.py – Exposes the /delete_document endpoint at line 2854 and manages the background_delete_documents task at line 1833.
• lightrag/lightrag.py – Contains the core delete_document method at line 3065 and the regeneration orchestration logic near line 3100.
• lightrag/kg/*_impl.py – Backend-specific graph deletion (e.g., neo4j_impl.py at line 215).
• lightrag/utils_graph.py – Provides the build_graph utility at line 42 for reconstruction.

The Deletion Workflow

When a deletion request is initiated, LightRAG executes a four-phase process: API acceptance, background processing, storage cleanup, and graph regeneration.

HTTP API Endpoint Reception

The delete_document endpoint receives the request and immediately returns a 202 Accepted response while spawning a background task. This prevents the client from blocking during the potentially long graph rebuild.

In lightrag/api/routers/document_routes.py (lines 2854–2863), the handler parses the JSON body and schedules the background worker:

# Conceptual usage of the endpoint

import httpx

async def delete_my_doc(doc_id: str):
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://localhost:8000/delete_document",
            json={"doc_id": doc_id},
        )
    if resp.status_code == 202:
        print(f"Deletion of {doc_id} queued – graph will be regenerated.")
    else:
        print("Failed:", resp.text)

Background Task Execution

The background_delete_documents function (line 1833 in document_routes.py) orchestrates the sequence. It first invokes the core deletion logic, then triggers graph regeneration to ensure the knowledge graph reflects only the remaining documents.

# Simplified logic from document_routes.py

async def background_delete_documents(doc_id: str):
    # 1. Delete vector chunks & file metadata

    await lightrag.delete_document(doc_id)
    
    # 2. Re-build the knowledge graph for remaining docs

    await lightrag.rebuild_graph()

Core Storage Cleanup

The delete_document method in lightrag/lightrag.py (line 3065) performs the low-level removal. It eliminates the document’s chunks from the vector store and delegates graph entity removal to the configured KG backend.

# lightrag/lightrag.py  (≈ line 3065)

async def delete_document(self, doc_id: str) -> None:
    # Remove embeddings / raw file references

    await self.storage.delete_document_chunks(doc_id)
    
    # Remove graph entities belonging to this document

    await self.kg.delete_document(doc_id)

Knowledge Graph Cleanup by Backend

Each knowledge graph implementation provides a storage-specific delete_document method to remove nodes and edges associated with the target document ID.

Neo4j Implementation

For Neo4j backends, lightrag/kg/neo4j_impl.py (line 215) executes a Cypher query that detaches and deletes all nodes matching the document identifier:

# lightrag/kg/neo4j_impl.py  (≈ line 215)

async def delete_document(self, doc_id: str) -> None:
    await self.session.run(
        """
        MATCH (n:Document {doc_id: $doc_id})
        DETACH DELETE n
        """,
        {"doc_id": doc_id},
    )

Similar implementations exist for other backends like postgres_impl.py and networkx_impl.py, ensuring storage-agnostic operation while maintaining graph integrity.

Automatic Knowledge Graph Regeneration

After deletion completes, LightRAG must regenerate the graph to purge any relationships that referenced the removed document and to discover new relationships among the remaining corpus. This process runs automatically within the background task.

The regeneration flow utilizes utils_graph.build_graph (line 42) and the orchestration logic in lightrag.py (line 3100):

# lightrag/lightrag.py  (≈ line 3100)

async def rebuild_graph(self) -> None:
    docs = await self.workspace.list_documents()
    chunks = await self.chunk_and_embed(docs)          # re-embed

    await self.kg.clear()                              # optional full clear

    await utils_graph.build_graph(chunks)              # fresh graph

This batch rebuild ensures that:

• Orphaned edges from the deleted document are eliminated.
• Cross-document relationships among remaining files are freshly computed.
• The vector index and knowledge graph remain synchronized.

Implementation Summary

To implement document deletion with automatic regeneration in your LightRAG deployment:

1. Expose the endpoint using the FastAPI router in document_routes.py to accept deletion requests.
2. Queue background tasks to prevent HTTP timeouts during the deletion and rebuild phases.
3. Call lightrag.delete_document(doc_id) to remove vector embeddings and invoke KG-specific deletion.
4. Execute lightrag.rebuild_graph() after deletion to reconstruct the knowledge graph from the surviving documents.
5. Monitor logs for completion signals, as the regeneration process runs asynchronously after the initial 202 response.

Summary

• Asynchronous processing – LightRAG returns HTTP 202 immediately and handles deletion in the background via background_delete_documents.
• Dual cleanup – The delete_document method in lightrag.py purges both vector stores (embeddings/chunks) and knowledge graph entities.
• Storage-agnostic – KG backends like Neo4j and Postgres implement their own delete_document methods to remove nodes and edges.
• Automatic regeneration – After deletion, rebuild_graph re-chunks, re-embeds, and rebuilds the entire knowledge graph to maintain relationship accuracy.
• Source locations – Key logic resides in document_routes.py (lines 1833, 2854), lightrag.py (lines 3065, 3100), and utils_graph.py (line 42).

Frequently Asked Questions

What happens if the knowledge graph regeneration fails during background processing?

If rebuild_graph encounters an error, the background task logs the exception and terminates without updating the graph. The system retains the state from the successful deletion step (removed vectors and graph entities), but the knowledge graph may be incomplete until the regeneration is manually retried or the service restarts with recovery logic.

Is document deletion synchronous or asynchronous in LightRAG?

Document deletion is asynchronous. The /delete_document endpoint returns a 202 Accepted status immediately after validating the document ID and spawning background_delete_documents. The actual storage cleanup and graph regeneration occur in the FastAPI background task queue, allowing the client to continue without waiting for the rebuild completion.

How does LightRAG handle cross-document relationships when one document is deleted?

Cross-document relationships that depend on the deleted document are automatically purged during the deletion phase when kg.delete_document removes associated nodes and edges. During the subsequent rebuild_graph call, the system re-analyzes the remaining documents and recreates only valid relationships that exist between the surviving corpus, ensuring no orphaned references remain.

Can I use this deletion workflow with any storage backend?

Yes. While the specific graph deletion query varies by implementation (e.g., Cypher for Neo4j at neo4j_impl.py line 215, SQL for Postgres), the core delete_document interface in lightrag.py abstracts these differences. As long as the configured vector store and KG backend implement the delete_document method, the automatic regeneration workflow functions identically across Qdrant, OpenSearch, NetworkX, and other supported backends.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}