# RAG-Anything Query Modes: How to Use Local, Global, Hybrid, and Naive Retrieval

> Explore RAGAnything query modes: local, global, hybrid, and naive. Learn how to optimize retrieval for latency and accuracy with the HKUDS/RAGAnything repo.

- Repository: [✨Data Intelligence Lab@HKU✨/RAG-Anything](https://github.com/HKUDS/RAG-Anything)
- Tags: documentation
- Published: 2026-04-22

---

**RAG-Anything provides six distinct query modes—local, global, hybrid, naive, mix, and bypass—that determine whether retrieval runs against the current document only, the entire knowledge base, both combined, via keyword matching, automatically, or not at all, each optimized for different latency and accuracy requirements.**

The HKUDS/RAG-Anything repository abstracts complex retrieval-augmented generation workflows behind a unified `aquery` API where the **`mode`** parameter controls the retrieval strategy. Understanding these **query modes** is essential for balancing search precision, computational cost, and answer completeness when querying indexed documents. All modes are implemented in the `QueryMixin` class and passed to the underlying LightRAG engine via `QueryParam` objects defined in [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py).

## Available Query Modes in RAG-Anything

The six supported values are documented in the docstring of `QueryMixin.aquery` at line 109 of [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py). Each mode instructs LightRAG exactly where and how to search for relevant context before the LLM generates an answer.

### Local Mode

**Local mode** searches only within the document that triggered the query, limiting the vector-store lookup to a small subset of chunks. This is the fastest path available because it avoids scanning the entire knowledge base. Use **local mode** when you are confident the answer is contained in the current file, such as when asking questions about a specific PDF chapter or markdown section.

### Global Mode

**Global mode** searches the entire knowledge base by running an embedding-based similarity search across the full index. This mode maximizes recall by checking all processed documents for relevant context. Use **global mode** for broad-scope questions that may need information from any document, such as asking about overall system architecture across multiple files.

### Hybrid Mode

**Hybrid mode** combines local and global results by first gathering top-k local chunks, then expanding with top-k global chunks, and finally merging and re-ranking them. This approach delivers the precision of local context while maintaining the ability to pull missing information from elsewhere in the corpus. **Hybrid mode** is ideal for most real-world queries where you need both focused and comprehensive evidence.

### Naive Mode

**Naive mode** performs a simple lexical match using keyword-based search instead of embedding similarity, executing no vector search at all. This provides deterministic, exact-string matching useful for debugging or when embedding services are unavailable. Use **naive mode** when searching for specific configuration keys, exact identifiers, or in low-latency scenarios where approximate semantic search is unnecessary.

### Mix Mode (Default)

**Mix mode** automatically chooses the best strategy based on current configuration: if a global index exists it behaves like hybrid, otherwise it falls back to local. This adaptive behavior makes it the recommended starting point when you are unsure which scope is needed. **Mix mode** is the default in all RAG-Anything examples and provides optimal performance without manual tuning.

### Bypass Mode

**Bypass mode** skips retrieval entirely and sends the raw user prompt directly to the LLM with only the system prompt attached. This mode incurs no retrieval latency or cost because no document lookup occurs. Use **bypass mode** for purely generative tasks where grounding is not required, such as creative writing or when the knowledge base is incomplete or irrelevant.

## Technical Implementation in the Source Code

The query mode selection logic resides in [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py), specifically within the `QueryMixin` class, while the high-level `RAGAnything` class in [`raganything/raganything.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/raganything.py) wires the configuration. According to the docstring at line 109, the **`mode`** argument tells LightRAG where and how to look for relevant context before generation. At line 161, the selected mode is packaged into a `QueryParam` object:

```python
QueryParam(mode=mode, …)

```

LightRAG interprets this parameter and builds the appropriate retrieval pipeline, whether that involves querying the local vector store, global vector store, executing a lexical grep, or skipping retrieval entirely. Default configuration values influencing this behavior are typically defined in [`raganything/config.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/config.py).

## Performance Trade-offs and Selection Strategy

Understanding the computational characteristics of each mode helps optimize your RAG-Anything implementation. **Local** and **naive** modes touch far fewer vectors, delivering lower latency suitable for interactive applications. **Global** and **hybrid** modes maximize the chance of finding needed evidence but consume more compute and increase response times. **Bypass** mode eliminates retrieval costs entirely but provides no document grounding.

When combined with vision-language model enhancements using `vlm_enhanced=True`, the selected mode still controls text retrieval while the VLM step adds image understanding on top of the fetched context.

## Code Examples for Each Query Mode

The following examples come directly from the RAG-Anything README (lines 606–614) and demonstrate practical usage of each mode:

```python

# 1️⃣ Default – let RAG-Anything decide (mix)

await rag.aquery("What is the main contribution of this paper?", mode="mix")

# 2️⃣ Local only – fast, document-scoped

await rag.aquery("Explain the algorithm in Section 3", mode="local")

# 3️⃣ Global only – search the whole corpus

await rag.aquery("Which datasets were used across all experiments?", mode="global")

# 4️⃣ Hybrid – combine local + global (most common)

await rag.aquery(
    "How does the proposed method compare to the baseline in Table 2?",
    mode="hybrid",
    top_k=10   # optional: ask for more candidates before re-ranking

)

# 5️⃣ Naive keyword match – no embeddings

await rag.aquery(
    "Find every occurrence of the string 'learning_rate' in the docs",
    mode="naive"
)

# 6️⃣ Bypass – ask the LLM directly

await rag.aquery(
    "Write a short abstract summarising the whole project",
    mode="bypass"
)

# 7️⃣ VLM-enhanced query (automatic when vision_model_func is provided)

await rag.aquery(
    "Describe the figure that shows the performance curves",
    mode="hybrid",          # retrieval mode

    vlm_enhanced=True      # force VLM image analysis

)

```

## Summary

- **RAG-Anything** supports six query modes implemented in [`raganything/query.py`](https://github.com/HKUDS/RAG-Anything/blob/main/raganything/query.py): local, global, hybrid, naive, mix, and bypass.
- **Local mode** provides the fastest retrieval by searching only the current document, while **global mode** scans the entire knowledge base for maximum recall.
- **Hybrid mode** merges local and global results for balanced precision and coverage, making it ideal for most production use cases.
- **Naive mode** uses lexical matching instead of embeddings for deterministic keyword searches.
- **Mix mode** automatically selects between hybrid and local based on index availability and serves as the recommended default.
- **Bypass mode** skips retrieval entirely for pure LLM generation when document grounding is unnecessary.

## Frequently Asked Questions

### What is the default query mode in RAG-Anything?

**Mix mode** is the default query mode in RAG-Anything. When using `mode="mix"`, the system automatically behaves like `hybrid` if a global index exists, otherwise it falls back to `local`. This adaptive strategy eliminates the need to manually select between retrieval scopes for most workloads.

### When should I use hybrid mode instead of global mode?

Use **hybrid mode** when you need both the precision of document-specific context and the comprehensiveness of cross-document search. While **global mode** searches the entire knowledge base uniformly, hybrid mode first retrieves relevant chunks from the current document then supplements with global results, making it more efficient for queries that primarily concern the active document but might reference external information.

### How does the naive mode differ from the other retrieval options?

**Naive mode** operates entirely through lexical matching rather than vector similarity, performing keyword-based greps instead of embedding searches. Unlike local, global, or hybrid modes which rely on vector stores and approximate nearest neighbor search, naive mode returns exact string matches, making it suitable for finding specific configuration parameters, function names, or when embedding services are unavailable.

### Does bypass mode still use the system prompt when skipping retrieval?

Yes, **bypass mode** skips the retrieval pipeline entirely but still attaches any configured system prompt to the request. Only the document context is omitted; the raw user prompt is sent to the LLM along with system instructions, making it suitable for pure generative tasks while maintaining conversation formatting and instruction following.