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

> Learn to implement document deletion and automatic knowledge graph regeneration in LightRAG. This guide shows how to delete vectors and entities, then rebuild the graph for integrity.

- Repository: [✨Data Intelligence Lab@HKU✨/LightRAG](https://github.com/HKUDS/LightRAG)
- Tags: how-to-guide
- Published: 2026-03-23

---

**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`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/neo4j_impl.py) at line 215).
- **[`lightrag/utils_graph.py`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/routers/document_routes.py) (lines 2854–2863), the handler parses the JSON body and schedules the background worker:

```python

# 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`](https://github.com/HKUDS/LightRAG/blob/main/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.

```python

# 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`](https://github.com/HKUDS/LightRAG/blob/main/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.

```python

# 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`](https://github.com/HKUDS/LightRAG/blob/main/lightrag/kg/neo4j_impl.py) (line 215) executes a Cypher query that detaches and deletes all nodes matching the document identifier:

```python

# 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`](https://github.com/HKUDS/LightRAG/blob/main/postgres_impl.py) and [`networkx_impl.py`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/lightrag.py) (line 3100):

```python

# 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`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/document_routes.py) (lines 1833, 2854), [`lightrag.py`](https://github.com/HKUDS/LightRAG/blob/main/lightrag.py) (lines 3065, 3100), and [`utils_graph.py`](https://github.com/HKUDS/LightRAG/blob/main/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`](https://github.com/HKUDS/LightRAG/blob/main/neo4j_impl.py) line 215, SQL for Postgres), the core `delete_document` interface in [`lightrag.py`](https://github.com/HKUDS/LightRAG/blob/main/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.