Fix: Add file_path field to full_docs storage

[danielaskdd]

Fix: Add file_path field to full_docs storage

Summary

This PR adds a file_path field to the full_docs storage layer, enabling better document tracking and citation capabilities. The implementation ensures compatibility across all storage backends (JSON, Redis, MongoDB, PostgreSQL) with special handling for PostgreSQL's existing doc_name column.

Relalted Issue: #2167

Changes Made

1. Core Pipeline (lightrag/lightrag.py)

Modified apipeline_enqueue_documents function:

full_docs_data = {
    doc_id: {
        "content": contents[doc_id]["content"],
        "file_path": contents[doc_id]["file_path"]  # Added
    }
    for doc_id in new_docs.keys()
}

Modified ainsert_custom_chunks function:

new_docs = {doc_key: {"content": full_text, "file_path": file_path}}

2. PostgreSQL Storage (lightrag/kg/postgres_impl.py)

SQL Template Updates:

• upsert_doc_full: Maps file_path → doc_name for INSERT/UPDATE operations
• get_by_id_full_docs: Returns doc_name as file_path for consistency
• get_by_ids_full_docs: Returns doc_name as file_path for batch operations

PGKVStorage.upsert() method:

elif is_namespace(self.namespace, NameSpace.KV_STORE_FULL_DOCS):
    _data = {
        "id": k,
        "content": v["content"],
        "doc_name": v.get("file_path", ""),  # Field mapping
        "workspace": self.workspace,
    }

3. Other Storage Implementations

No changes required for:

• JsonKVStorage: JSON serialization automatically handles new fields
• RedisKVStorage: JSON serialization in Redis automatically stores new fields
• MongoKVStorage: Document-based storage automatically accommodates new fields

Technical Details

Field Mapping Strategy

PostgreSQL uses a bidirectional mapping approach:

• Application → Database: file_path → doc_name
• Database → Application: doc_name → file_path

This preserves the existing PostgreSQL schema while maintaining a consistent application-layer interface.

Backward Compatibility

✅ Fully backward compatible:

• Existing documents without file_path will return empty string ("")
• PostgreSQL query uses COALESCE(doc_name, '') as file_path to handle NULL values
• No database migration required
• All storage backends gracefully handle missing fields

Impact

• Breaking Changes: None
• API Changes: None (internal storage only)
• Performance Impact: Negligible (one additional field per document)
• Database Schema: No migration needed (uses existing PostgreSQL doc_name column)