How to Run a Graph-Only RAG Query with HugeGraph AI

Yes, HugeGraph AI supports graph-only RAG queries through the RAGGraphOnlyFlow class, which traverses the knowledge graph without performing vector semantic search. You can execute this via the Python SDK using SchedulerSingleton, the REST API with the graph_only parameter, or the built-in Gradio demo.

Apache HugeGraph AI provides a specialized pipeline for graph-only retrieval-augmented generation (RAG) that answers queries exclusively through knowledge graph traversal. This approach leverages the structured relationships within hugegraph-llm to retrieve context without relying on vector similarity search, making it ideal when semantic embeddings are unnecessary or when precise graph relationships provide better answers.

Understanding the Graph-Only RAG Architecture

The graph-only functionality is implemented in hugegraph-llm/src/hugegraph_llm/flows/rag_flow_graph_only.py by the RAGGraphOnlyFlow class. When the prepare method receives a WkFlowInput with graph_only_answer set to True, it constructs a GPipeline that executes the following nodes:

• Keyword extraction via KeywordExtractNode to identify relevant graph entities.
• Semantic-ID lookup through SemanticIdQueryNode (executed but ignored when graph_only is enabled).
• Schema retrieval via SchemaNode and graph traversal via GraphQueryNode.
• Result merging and re-ranking through MergeRerankNode.
• Answer synthesis using AnswerSynthesizeNode to generate the final response.

The pipeline uses the VectorOnlyCondition node (lines 39-43) to branch execution. When prepared_input.is_vector_only evaluates to False, the flow selects the graph-only branch, effectively skipping vector retrieval operations.

API and Configuration Options

REST API Endpoint

The public API exposes graph-only retrieval through the /rag endpoint defined in hugegraph-llm/src/hugegraph_llm/api/rag_api.py. The RAGRequest model in hugegraph-llm/src/hugegraph_llm/api/models/rag_requests.py (lines 35-40) includes a boolean graph_only field that triggers the graph-only flow when set to True. When this flag is active, the request dispatches to the RAGGraphOnlyFlow pipeline.

Scheduler and Flow Registration

The SchedulerSingleton manages pipeline instances in hugegraph-llm/src/hugegraph_llm/flows/scheduler.py (lines 88-91). It registers the graph-only flow under the enumeration FlowName.RAG_GRAPH_ONLY defined in hugegraph-llm/src/hugegraph_llm/flows/__init__.py (lines 21-23). The scheduler maintains a reusable pipeline pool, instantiating new flows on-demand when schedule_flow is called.

Executing Graph-Only RAG Queries

You can trigger graph-only retrieval through three interfaces: the Python SDK, REST API, or demo UI.

Python SDK Implementation

Use the SchedulerSingleton to execute the flow programmatically:

from hugegraph_llm.flows import FlowName
from hugegraph_llm.flows.scheduler import SchedulerSingleton

# Initialise the singleton scheduler

scheduler = SchedulerSingleton.get_instance()

# Run a graph‑only RAG query

result = scheduler.schedule_flow(
    FlowName.RAG_GRAPH_ONLY,
    query="Who founded Apache HugeGraph?",
    graph_only=True,               # explicitly request graph‑only retrieval

    max_graph_items=30,
    topk_return_results=20,
)

print("Graph‑only answer:", result.get("graph_only_answer"))

HTTP API Request

Send a POST request to the /rag endpoint with the graph_only parameter:

curl -X POST http://localhost:8001/rag \
     -H "Content-Type: application/json" \
     -d '{
           "query": "What is the capital city of France?",
           "graph_only": true,
           "max_graph_items": 30,
           "topk_return_results": 20
         }'

The API returns a JSON response containing the synthesized answer:

{
  "query": "What is the capital city of France?",
  "graph_only": "Paris is the capital city of France."
}

Gradio Demo Interface

The built-in demo in hugegraph-llm/src/hugegraph_llm/demo/rag_demo/rag_block.py provides a UI option labeled "Graph-only" in the flow selector. Selecting this option internally invokes the same scheduler flow with graph_only=True, offering a no-code approach to testing graph-only retrieval.

Summary

• Graph-only RAG in HugeGraph AI bypasses vector semantic search, relying solely on knowledge graph traversal via RAGGraphOnlyFlow.
• The pipeline executes keyword extraction, graph schema retrieval, and graph queries through dedicated nodes, skipping vector retrieval via the VectorOnlyCondition branch logic.
• Access this functionality through the /rag REST API by setting graph_only=true, through the Python SDK using SchedulerSingleton.schedule_flow(FlowName.RAG_GRAPH_ONLY), or through the Gradio demo UI.
• Core implementation files include rag_flow_graph_only.py for the pipeline logic and rag_requests.py for the API model defining the graph_only boolean field.

Frequently Asked Questions

Does graph-only RAG completely disable vector search in HugeGraph AI?

Yes, when graph_only is set to True, the pipeline explicitly ignores vector search results. While the SemanticIdQueryNode still executes for workflow consistency, the VectorOnlyCondition node (lines 39-43 in rag_flow_graph_only.py) ensures that only the graph branch contributes to the final answer synthesis.

What is the default retrieval mode when calling the /rag endpoint?

According to the RAGRequest model in rag_requests.py (lines 35-40), the API accepts a graph_only boolean parameter. The specific flow executed depends on which FlowName the scheduler invokes; when using FlowName.RAG_GRAPH_ONLY, the system defaults to graph-only retrieval unless explicitly overridden in the request payload.

Can I adjust the number of graph items retrieved in a graph-only query?

Yes, both the Python SDK and REST API accept max_graph_items and topk_return_results parameters. These values control how many entities and relationships the GraphQueryNode fetches and how many results the MergeRerankNode returns to the AnswerSynthesizeNode for final generation.

Is the graph-only pipeline reusable across multiple queries?

Yes, the SchedulerSingleton maintains a pipeline pool and reuses instantiated flows. When you call schedule_flow with FlowName.RAG_GRAPH_ONLY, it either retrieves an existing pipeline from the pool or creates a new one on-demand, optimizing resource usage for repeated graph-only RAG operations.

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