Skip to content

Feature: Add /query/data API Endpoint for Raw Retrieval Data - #2100

Merged
danielaskdd merged 89 commits into
HKUDS:mainfrom
danielaskdd:return-data-only
Sep 14, 2025
Merged

Feature: Add /query/data API Endpoint for Raw Retrieval Data#2100
danielaskdd merged 89 commits into
HKUDS:mainfrom
danielaskdd:return-data-only

Conversation

@danielaskdd

@danielaskdd danielaskdd commented Sep 14, 2025

Copy link
Copy Markdown
Collaborator

Add /query/data API Endpoint for Raw Retrieval Data

Overview

This update introduces a new API endpoint, /query/data, designed to return raw retrieval data from the RAG process without LLM generation. This feature is crucial for data analysis, and use cases that require direct access to knowledge graph retrieval results (entities, relationships, text chunks).

By decoupling data retrieval from LLM generation, developers can gain clearer insights into the retrieval capabilities of the knowledge graph and perform fine-grained processing on the results.

Key Changes

1. New /query/data API Endpoint

  • File: lightrag/api/routers/query_routes.py
  • Changes:
    • Added the QueryDataResponse Pydantic model to define the structured data format for the response, including entities, relationships, chunks, and metadata.
    • Implemented a new POST route /query/data that calls the rag.aquery_data method to directly return the retrieved raw data without passing it to an LLM.

2. Introduction of the aquery_data Core Method

  • File: lightrag/lightrag.py
  • Changes:
    • Renamed the existing asearch method to aquery_data to clarify its function: performing asynchronous data queries only.
    • The aquery_data method now invokes different query strategies (e.g., kg_query, naive_query) based on the param.mode query parameter and uses the return_raw_data=True argument to fetch the final data before LLM processing.

3. Extended Functionality in kg_query and naive_query

  • File: lightrag/operate.py
  • Changes:
    • Added new function signatures for kg_query and naive_query using @overload. When return_raw_data=True, these functions return a dictionary containing the raw data instead of a generated text response.
    • In kg_query, when raw data is requested, the process returns early after _build_query_context, bypassing the LLM call.

4. Optimized Data Handling Process

  • File: lightrag/operate.py
  • Changes:
    • In _apply_token_truncation, data copies are now created for processing to prevent accidental modification of original data during truncation, enhancing code robustness.
    • The interface of the _merge_all_chunks function has been simplified for a more focused and clear responsibility.

How to Use

Send a POST request to the /query/data endpoint, compatible with the /query endpoint. The response will be a JSON object containing the following fields:

  • entities: A list of entities retrieved from the knowledge graph.
  • relationships: A list of retrieved relationships.
  • chunks: A list of relevant text chunks retrieved from documents.
  • metadata: Metadata about the query, including the query mode, keywords used, etc.

tongda and others added 30 commits September 1, 2025 02:19
…cts (entities, relations, chunks) in their raw data format.
• Skip cache when only_need_prompt is set
• Update only_need_context condition logic
• Prevent cache bypass in prompt-only mode
• Remove get_conversation_turns utility
• Pass history_messages to LLM directly
• Clean up prompt template formatting
- Replace json.dumps with line-by-line format
- Apply to entities, relations, text units
- Update truncation key functions
- Maintain ensure_ascii=False setting
- Improve context readability
- Delete history section from prompt
- Simplify user query response format
- Remove {history} placeholder variable
• Clarify max_tokens vs max_completion_tokens
• Add Gemini exception note
• Update parameter descriptions
• Add new completion tokens option
…parison

- Implement description length comparison in gleaning merge logic (extract_entities)
- Apply same logic to knowledge graph reconstruction (_rebuild_knowledge_from_chunks)
- Prioritize entities/relationships with longer descriptions for better quality
- Use list() instead of extend() for performance optimization when replacing
* Support `( and `( start patterns
* Support )` and )` end patterns
* Graceful fallback to warning logs
* Strip 2 chars for backtick variants
* Maintain existing bracket logic
- Expand bracket tolerance to support additional characters: < > " '
- Implement symmetric handling for both leading and trailing characters
- Replace simple string matching with robust regex-based pattern detection
- Maintain full backward compatibility with existing bracket formats
…elimiter to <|SEP|>

• Add robust delimiter fixing logic
• Update prompts for single-line format
• Consolidate 6 regex patterns into 3
• More efficient pattern matching
• Clearer comments and examples
• Same functionality, less code
• Better maintainability
- Extract regex fixes to utils module
- Add case-insensitive delimiter handling
- Track timestamps for cache hits/misses
- Add timestamp to entity/relationship objects
- Sort descriptions by timestamp order
- Preserve temporal ordering in merges
• Fix completion_delimiter reference bug
• Add case check before lowercase conversion
• Improve delimiter corruption handling
• Optimize redundant processing logic
• Fix typo in error log message
• Clarify format requirements in prompts
• Make extraction instructions clearer
• Improve user prompt consistency
• Fix typo in error log message
• Clarify format requirements in prompts
• Make extraction instructions clearer
• Improve user prompt consistency
- Add debug logs for malformed records
- Fix regex for consecutive delimiters
- Handle missing closing brackets
* Remove trailing whitespace
* Fix function signature ellipsis style
- Add debug logs for malformed records
- Fix regex for consecutive delimiters
- Handle missing closing brackets
- Add QueryDataResponse model
- Implement /query/data endpoint
- Add aquery_data method to LightRAG
- Return entities, relationships, chunks
- Remove processing_info generation from _convert_to_user_format function
- Move all metadata generation (keywords, processing_info) to kg_query and naive_query functions
- Simplify _convert_to_user_format to focus only on data format conversion
@danielaskdd
danielaskdd merged commit ad0a533 into HKUDS:main Sep 14, 2025
1 check passed
@danielaskdd
danielaskdd deleted the return-data-only branch September 16, 2025 19:18
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.

3 participants