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

> Discover how to run graph-only RAG queries with HugeGraph AI. Utilize RAGGraphOnlyFlow for efficient knowledge graph traversal without vector search. Explore Python SDK and REST API options.

- Repository: [The Apache Software Foundation/incubator-hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)
- Tags: how-to-guide
- Published: 2026-02-24

---

**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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/src/hugegraph_llm/api/rag_api.py). The `RAGRequest` model in [`hugegraph-llm/src/hugegraph_llm/api/models/rag_requests.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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:

```python
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:

```bash
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:

```json
{
  "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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/rag_flow_graph_only.py) for the pipeline logic and [`rag_requests.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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.